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Of Studies 
Francis Bacon 1561 — 1626 


CHAPTER 1 
_ _ Introduction 


This book is not intended for the absolute beginner, but for someone who 
has used machine code programs from books or magazines and feels the 
| urge to try his or her hand. 

To those of you who are still interested, this book is not a thesis on the 
instruction code or the internal operations of the Spectrum. If you do not 
already own one, you will need to obtain a book which explains how the 
Z80 functions — most things I shall explain, but some things will be 
omitted through over familiarity or because I did not set out to detail them. 
I do include a synopsis of the available instructions and their execution 
times but have not touched on peripheral programming, the interrupt 
vector register nor the refresh register. My purpose is to present an 
introduction to machine code programs which can interface with BASIC, 
which I assume that you already know thoroughly. 

Why should you use machine code? 

For total freedom from the restraints of BASIC and an increase in speed. 
I have included an array sort routine (Chapter 10) which is about 125 times 
faster than its BASIC equivalent (and then show how you can double that). 
On the other hand the errors make themselves known that much faster. 

For the machine code programs I have used a simple assembler by 
Picturesque. 

Always remember that if you can see a logical way of solving a problem 
then that problem can be solved. The hardest thing for the beginner is 
sticking it out, the resolution to persevere until the last error is removed 
and the code runs correctly. 

Do not, to begin with, attempt more than one or two hours at a stretch, 
and do keep notes on your errors. After a few weeks the worst of the nerves 
will be over and you will have become well’acquainted with machine code. 

For any problem, write down what you want to do and then draw flow 
diagrams. If you can’t do a bit of the problem put it in a little box and carry 
on with the main problem; later go back and work on the boxes as if they 
were full grown problems in their own right. 

Finally, never forget: the true programmer exists in one of two states: the 
depths of despair because the program is not working, or the highest 
elation because it is known why the program is not working. 
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CHAPTER 2 
About Programming 


‘An engineer was called from afar; the 
machine would not work; he pondered 
the problem; he called for a hammer; he 
dealt the thing a resounding blow; it 
worked. Much later the bill arrived: 


Transport and travel £50.00 
Hitting the machine £00.01 
Knowing what and wheretohit £500.00 
Total £550.01 (+ VAT).’ 


(Modernised Apocryphal) 


Programming is far more an art than a science. Science is involved, for 
the rules imposed by the machine code instructions and any operating 
system admit of no flexibility. But the presence of the finest ingredients 
hardly implies great cuisine if the cook is a gorilla — on the other hand, a 
great cook can conjure a feast from the most unpromising beginnings. 

There is constant interplay amongst eight things: 


Reliability 

Simplicity 

Testability 

Speed 

Size 

Documentation 
Program environment 
Program specification 


Reliability 
Djikstra’s conjecture: 

If a program has N instructions, each having a probability p of doing the 
right thing, then the probability of the program doing the right thing is of 
the order of p’. 

If the program is to loop L times, then the probability is of the order of 
p%!, which means that if p is not equal to 1 then the program is not worth 
running. 
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Every fault in a program ought to be investigated, explained and 
corrected. A faulty program is not worth running, a misplaced comma has 
cost millions before now. 


Simplicity 

There is no merit in making programs needlessly convoluted. The whole, 
no matter how complicated, can always be broken down into a few simple 
parts and these parts further reduced to simpler parts. I find that a very 
good way to test a program is to draw lines on a listing from jump 
instructions to the relevant labels. The results are usually self evident. 


Testability 


Much has been written about testability; all I shall say here is that 
simplicity of structure makes testing that much easier. You can have more 
combinations of bit pattern in a mere 40 bytes than there are atoms in the 
universe. 


Speed 


Each instruction takes a finite time to execute and there are always several 
possible instruction mixes to produce the same result. If you havea piece of 
program which seems to be slow to produce results, examine it for loops 
within loops within loops. Improvements in speed may require changes in 
data structure which may mean that the program becomes bigger. 


Size 
‘Anybody can build a bridge, but only an engineer can, just.’ 

The size of a program is the sum of its two parts — the instructions and 
the data area. 

Data should never be written into and be part of a program except 
(perhaps) in test programs. The program should be given a pointer to the 
location of its data and be allowed to work from there. 

The number of instructions can nearly always be reduced. The more 
straightforward the program construction the easier and more effective the 
reduction will be. 


Documentation 


A program or subroutine without proper and adequate documentation 
might as well not exist. You can retain sufficient memory of a piece of a 
program for about three months to prompt you, with a listing, as to how 
and why and what. Beyond those three months the program becomes a 
liability. 


12 


nd 
as 


at 
re 


Chapter 2 About Programming 


Documentation does not need to become a magnum opus, just: 


List of entry conditions a) registers 
b) special locations 


List of exit conditions a) registers 
b) special locations 
c) preserved registers 
d) flags set 


Brief description of the function 


These, together with a listing and flow diagram should be kept in a good 
note book with stiff covers. If you can also keep the original source code on 
tape so much the better. I use message cassettes myself, they seem to do 
quite well. 


Program environment 


A fancy way of saying what extra peripherals you have beyond the TV 
screen. You must always tailor your output to suit. What looks impressive 
in flashing, scintillating colour will look very different on a ZX printer. 


Program specification 


This is left to the end because everything else affects and is affected by it. It 
may be necessary to go round the whole loop several times to arrive at an 
acceptable compromise. 

There are particular aspects which must be considered if you are 
producing a program for someone else: 


a) Do you understand what he says he wants? 

b) Is what he says he wants a true expression of what he needs? Remember 
that you and he have to have a common appreciation of the problem to be 
solved. 

c) Can you see the problem as one of a more general sort that you have 
already solved, or, more generally, have you solved something like it 
already? Is this problem going to be the first of a series? Would it be better 
to write a more general program for future needs? For example, given the 
need to integer arithmetic extending over seven bytes, might it not be better 
to devise general solutions extending over N bytes and then set N to 7 for 
the specific case? 

d) If the problem is a large one, time spent designing the data base can 
repay vast dividends in time needed to extract data. All the data referring to 
a major item should be stored together so that it can be got at through a 
single page register. Different settings of the page register are then used to 
point to different data items. 


13 


Machine Code Applications Sor the Spectrum 


e) When you have a solution scheme worked out you will also have some 
questions to ask, so go back to a) above and start again. 


TS TPE SERRE NE 


SERED CIEL MN BF PRETEND OE 
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CHAPTER 3 
Instructions 


The instruction codes and their actions on the flags are given condensed 
form in Figure 3.1 and Figure 3.2 together with their allowed address 
combinations. These tables are no substitute for the books mentioned in 
Chapter 1. 


Form of Figure 3.1 
column description 


1 operation mnemonic 
2 symbolic operation 
3 allowed address combinations (where two addresses are 


allowed the two groups of possibles are separated by a space). 


The numbers under some of the addresses indicate the execution times of 
the associated operation (in computer clock cycles). 


N indicates that a 1 byte value may be used 

NN indicates that a 2 byte value may be used 

(NN) indicates that the address of a byte is to be used 

d is a 1 byte page offset to be used with a page register 


DISP __ is the displacement to a nearby instruction 


The stack 


The stack is a concertina-like list which stores items in a first-in first-out 
(FIFO) form. It is like a pile of cards — the first one you place on top is 
the first to be removed, but to confuse matters it is held in memory 
‘upside- down’. The top of the stack (ie where the last item added is) is at 
a lower address than the bottom (ie where the very first item lies). The 
Stack Pointer SP is a 16-bit register which points to the address of the 
last item on the stack. 

Normally the stack is used for storing return addresses from 
subroutines, in the form of a pair of bytes, and a CALL puts a pair on 
the stack (and decrements SP by two), and a RET will remove it (and 
increment SP by two). However, there are two other types of instructions 
that use the stack — PUSH and POP. When a 16-bit register is PUSHed 
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Figure 3.1a 
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Figure 3.1b 
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Figure 3.1c 
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Chapter 3 Instructions 


BLOCK ano REPEAT LOAD AND COMPARE 


FLAGS « A-(HL) | COMPARISON CP 
HL© HL-1 
Bc< Be-1 
HL€ HL+1 
Bc¢e Bc-1 


HL<© HL-1 
BC+ BC-1 REPEAT UNTIL A =(HL) 
OR Bo=g 


ALL COMPARISON INSTRUCTIONS 
LEAVE THE A REGISTER UNALTERED 
BUT JUST SET THE FLAGS ACCORDING 
TO THE SUBTRACTION. 


D ORI REFERS TO DECREMENTING 
OR. INCREMENTING THE CONTENS OF HL. 
IN ALL CASES THE BC REGISTER PAIR 
IS DECREMENTED 


HL© HL+1 
CPDR | BC < BO-1 REPEAT UNTIL A =(HL) 
OR Bc=9 


LDL 


LDOR 


LDIR 


IND 


INI 


INDR 


INIR 


OuTD 


OUTIL 


OTDR 


OTIR 


LOAD 


DE< DE+1 
HL© HL+1 
Bo< Be-1 
DE< DE-1 
HL€ HL~-1 
Bc Be-1 
DE < DE +1 
HL© HL+1 
BC Bc-1 


REPEAT UNTIL BC = 


REPEAT UNTIL BC=4 


(HL) < (c) 
B<€ B-1 
HL <€ HL-1 


B<¢ B-1 

HL© HL+1 

B+ B-1 

HL HL-1 REPEAT UNTIL B = @ 
B< B-1 

HL€ HL4+1 REPEAT UNTIL B= 


(Cc) (HL) 
Be B-1 
HL€ HL-12 


Be B-1 
HL€ HL+1 


Be B-1 
HL ¢ HL-1 REPEAT UNTIL B= 


Be B-1 
FHL < HL+1 REPEAT UNTIL B= 


DECREMENT AFTER EXECUTION 


DECREMENT AFTER EXECUTION 


BLOCK anp REPEAT ineut/ourPut 
BC CONTAINS (INPUT) PORT ADDRESS, HL CONTAINS DATA ADDRESS 


DECREMENT BEFORE. EXECUTION 


DECREMENT BEFORE EXECUTION 


BC CONTAINS (OUTPUT) PORT ADDRESS, HL CONTAINS DATA ADDRESS 


DECREMENT BEFORE EXECUTION 


DECREMENT BEFORE EXECUTION 
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Figure 3.2 
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FLAG SETTING INSTRUCTIONS 


ARITHMETIC 
8BIT ADDA,r; ADC A,r 
SUB r ;,S8Cr 
cP r 
NEG 
\6BIT ADD 
ADC 
SBC 
LOGICAL. AND r 
OR r ;xXORr 
CPL 
ROTATE RLA 7RRA 
RLCA =; RRCA 
RL rt >. ARs 
Ricr ;RRCr 
SHIFT SLAr ;SRAr 
SRLr 
BITEST BIT br 
YO TRANSFERIN 1, €) 
INI 7 IND 
OUTI ; OUTD 
INIR ; INDR 
OTIR ;OTDR 
BLOCK 
MOVE LDI ; LDD 
LDIR ; LDDR 
SEARCH CPI ; CPD 
CPIR ;CPDR 
QTHERS CCF 
DAA 
DEC r 
INC r 
LD A, 1 
LD A,R 
RLD 7, RRD 
SCF 
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FLAGS (IN F REGISTER) 


[s{z] [| |PvIN [cy] 


COMMENTS 


FLAGS SET FOR A-r 
FLAGS SET FOR A=-A 


** x ¥ 
a a 


* 
* 
* 
* 
¥ 


*K KKK * 


<< 


| eel k * kK KK K 


* 


AzA 
g || ROTATE A 
@ @|%*| ROTATE A AND Cy 
*|% @ @|*| ROTATE R 
*|* @ @|%| ROTATE R AND Cy 


BIT B OF r PLACED INZ 


x 
Me BLOCK 1/0 
1 $=0 IF B#¢9 
$=1 IF B=@ 
1 
¢ g 4¢ SET IF BC=1 
© @ 
* 1 $ SET IF A = (HL) 
* 1 ; # SET IF BO=1 
g Cy =Cy 
%1% * P ADJUST RESULT TO CONTINUE 
¥ | % * via BCD ARITHMETIC 
*/% ¥ Vi@ 
*|* @ $|@ Be INTERRSPT ENABLE FLIP 
| * @ $|@ FLOP IS MOVED To P/V 
*| % @ P|@ LEFT AND RIGHT BCD ROTATE 
@ g 


NOTES ON THE TABLE 


UNSET 
SET 


P/V SET AS A 


DSONOMHS WH 


g 
1 
P 
Vv 
* 
b 
a 
$ 
. 


Ss 


NO SYMBOL ~ NO ACTION 


P/V SET ACCORDING TO PARITY OI RESULT 


RESULT OF OVER~- OR UNDER - FLOW 


MAY BE SET OR UNSET 
1S A BIT NUMBER @ (1)7 
A SINGLE REGISTER OR A BYTE VALUE 


3 SEE ADJACENT COMMENT 
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its two bytes are put on the top of the stack, and SP decremented by two. 
The opposite is POP which places the values of the top two bytes on the 
stack into a 16-bit register. SP is then incremented by two. 

Repeated PUSHing will eventually reduce SP until it starts to 
overwrite your program or data, and unfunny things will start to happen, 
usually resulting in a system reset. 

As-long as POPS and PUSHs are kept in step the SP pointer will not 
‘run away’; usually 200 or so bytes are sufficient but with deeply nested 
subroutines and more advanced programming than is dealt with in this 
book you will perhaps need more. Remember that the higher you set the 
head address of your program the less room there is for the stack. 

If POP and PUSH become unbalanced over a subroutine then, in 
general, the subroutine cannot exit correctly (a very common beginner’s 
problem). However, if on entry to the subroutine, you store the SP value 
in some address (which the stack is not going to over-write!), you can 
always exit correctly from the deepest level of nesting, by resetting SP 
from the stored value and executing a RET instruction, eg 


GRAFS LD (ADDR),SP 


EXIT LD HL,(ADDR) 
LD SP,HL 
RET 


Everything that was left on the stack still exists but is just abandoned 
and will be overwritten by subsequent PUSH operations. 
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CHAPTER 4 
Number Representation 


‘When J use a word,’ Humpty Dumpty 
said, in a rather scornful tone ‘it means 
just what I choose it to mean — neither 

more nor less.’ 

‘The question is,’ said Alice, ‘Whether 
you can make words mean so many 
different things.’ 

‘The question is,’ said Humpty 
Dumpty, ‘which is to be master — that’s 

all ’ 


(Alice through the Looking Glass) 


Given the content of any byte very little can be said about it except its value. 
Its meaning depends on the programmer or program which gave the byte 
that particular value. 


Example 1 

If the byte is a copy of the F register (FLAGS) then you must refer to Figure 
3.3 and even then you may need to work back through the program to 
determine which operation on what data set a particular bit. 


Example 2 

It may be part of a Spectrum standard floating point number (see Figure 
4.1). Before you can assign a meaning to the byte you must determine 
which of the five possible bytes it is. 


Example 3 
It may be one byte of a 16 bit integer — again which byte? 


Example 4 

It may be a genuine byte value such as an ASCII character code or a 
Spectrum token, in which case the meaning can be determined by 
inspection of Figure 4.2. Note that when and if you use an RS232/V24 type 
of interface you will almost certainly need to insert transmission control 
codes and may also be required to set or unset the MS bit of each ASCII 
character according to the parity required by the peripheral. 
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Figure 4.1 
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Figure 4.2 
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Example 5 


It may be (part of) an instruction code. If you start off in the wrong place 
the result will be gibberish. 

There is no way of knowing, from the byte alone, what it is. If, however, 
the location of the start of the machine code program can be determined 
the rest of the program follows logically and in running is all sorted out by 
the hardware. 


Floating point numbers (see Figure 4.1) 


Read the Spectrum manual pages 169-170. What follows is a note on 
manipulating fp numbers. 

The Sign of the characteristic is in the lowest addressed byte. 

When working with fp numbers, always adjust the size of the exponent 
such that the bit after the characteristic sign bit is the inverse of the sign bit; 
that is, the characteristic begins either 01 or 10, never 00 or 11. 

To add or subtract fp numbers, first adjust the exponents to be the same 
(shift the characteristic of the lower fp number right as its exponent is 
increased) then add or subtract the characteristics as required and correct 
the exponent for over- or under-flow if need be. This shifting to equalise 
exponents is known as normalisation. 


Multiplication and division of fp numbers 


1 Don’t, unless you have to. 
2  Ifyoumust * a) add or subtract exponents 
b) multiply or divide the characteristics 
or c) get the BASIC to do it for you! 


Data structures 


Data structures can be as simple or complex, long or short, as you wish, can 
unravel and can find room to handle. Each set of problems has its own 
solutions. 

Suppose that much alpha-numeric data has to be handled, we have A—z, 
A-Z, 0—9, space and punctuation. If we introduce a shift character to 
distinguish between upper and lower case and put digits in the opposite 
case to punctuation, then the whole can be squeezed into 40 separate codes. 
Now 40 * 40 * 40 = 64000 and 16 bits in two bytes has a maximum value of 
65535. For the price of some coding we can get three characters where there 
were only two before — an increase of 50% in the available storage. 

Again there is another scheme: there are 26 * 26 = 676 letter pair 
combinations, aa, ab, ac, .... ZX, Zy, ZZ, by no means all of which exist in 
English (or any other language for that matter). It may well be that in a 
particular application, less than 256 such pairs exist; in such a case the 
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input may be coded at two letters per byte with a resulting doubling of the 
storage capacity. 

If we are handling large arrays of numerical data, whose entries are 
mostly empty (the so-called sparse arrays) we may have to design 
techniques for handling the data, not as arrays, but in terms of the non null 
elements and their locations. This will be slow but at least we will be able to 
handle the problem. 


Signed and unsigned arithmetic 


Signed arithmetic uses the MS bit of the value to indicate the arithmetic 
sign of the remaining bits. In unsigned arithmetic you keep track of the 
signs of the values of the variables. Usually it suffices to ignore the sign bit 
as is done in addressing (but keep an eye on the carry flag). 
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Addressing 


Addressing refers to the method by which data or constants stored in 
memory are read into the Z80 registers, and is a very important concept. 
The Z80 has many modes, some more useful in certain applications than 
others. 

Be very clear in your own mind whether you are using 8 or 16 bit 
variables. Addresses are always 16 bit values and refer either to a byte or 
the lower of the two bytes used for a 16 bit value (but remember that in the 
BASIC program area the Spectrum system has line numbers swapped 
around). 

There are several methods of getting at data: some are outlined below: 


Direct 
The location is known and has a name or numerical value. 


eg LD HL,(23626) will put the contents of 23627/8 into the 
HL register pair. 
LD A,(23627) will put the contents of byte 23627 into 


the accumulator or A register. 


Direct + fixed offset 
At run time this is identical to the direct method. 


eg LD B,(PHRED +5) PHRED is a value determined by the 
assembler at assembly time. 


With most assemblers the address can be generated from any mixture of 
labels and values together with + and — signs. Also a label may be 
assigned a value rather than having a value determined for it by the 
assembler. 


Indirect 
The address of the required data is held in some known location. 


eg LD H1,(PHRED) HL is loaded with the address. 
LD B,(HL) B loaded with the byte addressed by the 
content of HL. 
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Page addressing 


Page addressing, also known as Indexed Addressing uses two 16 bit 
registers — [X and IY. A page in this context is an area of not more than 256 
bytes whose head address is loaded as a 16 bit value in the IX (or IY) 
register. There are assumed to be several such pages, all laid out in the same 
order, each containing data for an individual item — see Chapter 10 for an 
example. Data is then handled by means of fixed offsets relative to the head 
of each page. 


eg LD A,(IX+5) will load A with the 6th byte of the page 
pointed to by the address currently held 
in IX. 


The method becomes more transparent if the fixed offset is given a name 


indicating the contents. Consider processing examination results. Each 
student is given a page, organised thus: 


BYTENO. CONTENTS 


0 
Student No. 
1 
2 Marks Mathematics 
3 beet English 
4 hrs Physics 
5 
6 
ger oF 


We can then code: LD A,(IX+ PHYSICS) so long as we have let the 
assembler know that PHYSICS has the value 4. To load HL with the 
student’s number we have to code: 


LD L,dxX+0) to load the low order byte 
LD H,(IX+1) to load the high order byte 


To move on to the next student we need only add a suitable constant to 
the page register. Page 180 of the Spectrum manual says that the IY register 
should not be used, but this is not strictly true. Although its value should 
never be altered, it is always set to 23610, and it can be used to access some 
of the system variables. For example, to set bit 1 of FLAGS the instruction 
would be 


SET 1,(1Y +) 
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Multiple indirect 


If we have access to only the address of the value, we have to repeat the 
process used to extract an indirect address. There is no theoretical limit to 
the depths to which one can sink in this process though I should consider it 
unreasonable to attempt more than three levels of descent. 


Chaining (see Figure 5.1) 


This is a method of linking (usually blocks of) data together so that a rapid 
search can be made. Chaining requires that each data item carries with it 
the address of one or more related data items. These addresses are known 
also as pointers. Chaining can be forward, backward or both together. The 
deletion of an item from a chain is accomplished by pointing around it, an 
item not pointed to does not exist. 

It is usually necessary to produce a ‘garbage’ collection routine to 
reorder data and physically remove deleted entries from chained data. 

Note that several independent chains can link through the same data (so 
long as pointer space is supplied). 

The Spectrum BASIC program is a part forward chain. Each line carries 
what amounts to a pointer to the head of the next line. Forward searching is 
easy, backward searches (such as GOTO... a previous line number) are 
fresh searches from the beginning. 


Computation of addresses (and instructions) 


When working with a variety of addresses, it is sometimes tempting to 
construct the address (or instruction), enter it into the code and then obey 
it. 

This technique is not to be recommended, but may be tolerated, 
especially where speed and size are of importance. I do use it and all I shall 
say is ‘be careful’. Remember also that you cannot use the technique if the 
program is going to be loaded into a PROM or ROM. 


Notes 


1 Only use it in subroutines, never the ‘main line’ of a program. 

2 On entry to the subroutine, be sure that you know what the sate of 
any computed instruction will be. Never compute an instruction for 
‘next time round’. 

3 Be very aware of how the assembler you use assembles the 
instructions that are modified — some instructions can be assembled 
in different ways: 


eg LDHL,(NN) can be coded (hex) 
2A—nl-n2 
or EX-—6B-nl-n2 
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Figure 5.la 
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Figure 5.1b 
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(The code examples in this book, to the best of my knowledge, use an 
assembler which produces the shorter of two equivalent forms.) 


4 Ifyou label the instruction, then the label has the address value of the 
first byte. 

5 Remember, when you document or publish the code, to draw 
particular attention to what you have done. Another person’s 
assembler may use the other assembly option or you may change 
assembler. 
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CHAPTER 6 
Simple Beginnings 


Introduction 


This chapter deals by example with two essential aspects of machine code 
programming; execution times for a piece of program and the passing of 
information into subroutines. I also attempt to give some insight into the 
way in which solutions develop. I regret that I know of no way in which 
years of experience can be grafted into the beginner. As you gain 
experience look back over your earlier efforts and wince, the more you 
wince the more you have learned. 


Clearing the display buffer; an essay on execution times 


Anelementary routine to clear the 6144 bytes of the display buffer, starting 
at 16384. 
My first thought was along the lines of: 


LD BC,6144 1 
LD HL,16384 2 
CLRE LD A,0 3 
LD (HL),A 4 
INC HL 5 
DEC BC 6 
LD A,B zt 
OR c 8 
JR NZ,CLRE 9 


which works, but is most inelegant. 


Note, however: 


a) Lines 7, 8 and 9 as a means of testing BC = 0 since a double register DEC 
or INC operation affects no flags. 
b) Instructions 3 and 4 can be amalgamated; I forgot that LD (HL),0 is a 
valid byte instruction. 

The loop 3/4 to 9 requires 37 clock cycles (see Figure 3.1) and is executed 
6144 times to give a requirement of 227300 clock cycles. Can we do it 
faster? 
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Version 2 
LD HL,16384 = 1 
LD C,24 2) 
LIN3 LD B,0 3 
LIN4 LD (HL),0 4 
INC HL 5 
DJNZ LIN4 6 
DEC Cc 7 
JR NZ,LIN3 8 


The inner loop, the main time consumer in any such routine, requires 
6144*29 = 178000 clock cycles, which is some 78% of the requirement of 
the first attempt. 

There are however problems if and when one wishes to generalise the 
solution which depends on 6144 being equal to 24*256: and are B and C 
correctly set up for the DEC and JR operations? 

We haven’t come to the end of the road yet. What we have tacitly done is 
to load the same location into successive locations. Suppose we cleared 
location 0 and then moved location 0 into location 1, and then moved 
location 1 into location 2 etc. Put another way what happens if we used the 
LDIR operation: 


LD HL,16384 = 1 
LD DE,16385 2 
LD BC,6143 3 
LD (HL),0 4 
LDIR 5 


and everything is done by LDIR 6143 times at 21 clock cycles a time. The 
time is thus 129000 cycles, or 57% of the first attempt. 

If we attempt to put all the variables into parameters and make a fully 
fledged subroutine out of this, to be fully general, we will have all the 
complexities of picking up the parameters. Just now this will be more 
trouble than it is worth. 

With a minor change to line 4 we make a clear display subroutine CLRD 
(Listing 6.1) which we enter with A=0 and record that all registers are 
destroyed. 


Setting up the attributes area 


A straight crib is in order here, just change the values assigned to HL, DE, 
and BC and give the routine a new name, SETA, which is entered with A= 
required attributes byte. 
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1235 CLRD 
1340 
1345 
1350 
#355 
1360 
1365 
1370 
“8 1375 
of 1380 
izes 
le 1290 


is 
d Listing 6.2 
d 


0745 WALT# 
O746 
0747 
O748 
O7F749 
O7350 
O731 
0/752 
e Os4> 
0754 
y O7355 
e 0756 
e o7357 
0760 
O761 
0763 
O7&3 
O7 64 
07465 


LWATT 


LWATU 
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HL, 16384 
DE, 16385 
BC, 4143 
(HL) ,O 
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I make no claim that the routines in this book are anywhere near 
minimum execution time or minimum length. Two or three people in 
competition should be able to make significant savings in time and space in 
most of the subroutines. 


Wait and the passing of data into subroutines 


When working with a machine code program, it is quite easy to execute 
output to the display faster than it can be displayed — certainly far faster 
than it can be comprehended. We need a routine that slows things down. 

Going back again to the CLRD routine yet again, the LDIR operation is 
fairly slow. If it were entered with HL = DE and BC =0 it would consume 
65536*21 clock cycles or about a + second at an 8 Mhz clock rate. So we can 
code the WAIT routine (Listing 6.2 and 6.3) taking care to save all the 
registers and restore them afterwards so that we can insert CALL WAIT at 
any point we wish without disrupting things. 

If we want a still longer wait we can put a call of WAIT inside another 
loop to get a wait of 60—70 seconds (routine LWAIT). 

While we are dealing with the WAIT function, it is often an idea to be 
able to wait until a key is pressed, and while we are doing this we can set 
specific key options (for use later on with data entry, cursor movement, 
games etc.). 

The answer to ‘how?’ is in location 23560 of the Spectrum variables 
area. This contains the code for the last key pressed. Remember the 
Spectrum interrupt system is running all the time your routines are 
working, (you are, in jargon, time sharing with it), so we can just loop, 
reading 23560 until the code we want appears. 

There are two problems to be answered 


a) How do we form the list? 
b) How do we tell the routine where the list is? 


Commentary 


The list must contain two things, a character code and an address to be 
accessed when that character is met. Some assemblers do not allow an 
address to be put into a list and the address may be so far away that a 
relative or displacement jump may not be used. An entry in the list must 
look like: 


Character code 
JP ADDRESS 


What about the length of the list? 
We could work out the length of the list beforehand and pass it into the 
routine in a register, but if we want to add or delete list entries this must be 
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O520 
O525 
OS30 
O3535 
O540 
o545 
O550 


OSS5 


O3560 
03565 
o870 
OS75 
O35B0 
O385 
OS9O 
O3595 
0600 
0605 
0610 
9615 
0620 
04625 
0630 
Q4635 
0640 
0645 
0650 
0655 
0660 
665 
0670 
0675 
0480 
0685 
0690 
9695 


PAUSE 


PAUS 1 


CHARS 
LASTE 
PEK EN. 


TED 


NXBYT 


MATCH 
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AF 

BC 

DE 

HL. 

A, (LASTE) 
oO 

Z,FAUS1 
(CHARS) ,A 
A,o 
(LASTE) ,A 


2odaQ 

HL. 

HL. 

A, (LASTE) 


O 

Z4 FREY. 
B 

Z, MATCH 
DE ,4 

Hi DE 
NABYT 
HL. 

BC 

B,A 

A,® 
(LASTE) ,A 
CHL) 
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Flowchart 6.1 


IFKEY WAIT FORA (SPECIFIED) KEY TO BE PRESSED 
IFKEY 


LOAD HLFROM STACK (T0 GET HEAD OF 
RESTORE STACK PARAMETER LIST) 


WAIT FOR A KEY 


INTO A (LAST KEY PRESSED) 


THIS LOOP 


A =(HL)READ CHARACTER 
POINTED 10 BY HL 


NO 


@ MARKS THE END OF THE PARAMETERS 
SO GO BACK AND CONTINUE WAITING 


CHARACTER MATCHES 


ENTRY IN LIST 
MOVE HL TO POINT TO HL=HL+1 
oP POPTO MIMIC ACTION OF RET ON STACK 
INSTRUCTION IN LIST SET LASTK =@ (FOR NEXT ENTRY) 


EXECUTE JP (HL) TO GO TO ENTRY IN THE UST 
WHICH MUST BE. THE INSTRUCTION 
TO LEAVE THE LIST 


EXIT 
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changed as well. A better way is to sacrifice a character code and mark the 
end with that. I use 0 as it is unused anyway and is easily tested for. 
The list now looks like: 


Code 1 

JP ADDRI 
Code 2 

JP DDR2 
nop 


A form of the list has been settled, how do we tell the routine where it is? 

There are two schools of thought here. One says that lists and suchlike 
constants should be kept neatly segregated in a section. The other says that, 
as far as possible, all the constants should be found reasonably close to the 
routines which require them. 

I tend toward the second school in this instance, as any routine becomes 
more rather than less self documenting. So, if we call the routine IFKEY 
(which tends to be self explanatory) its use could look like this: 


CALL IFKEY 
DEFB “A” 
JP AREAD 
DEFB “+” 
JP INCR 


(DEFB puts a character code in the code). The call of IFKEY hangs the 
program until either the A key is pressed (in capital shift) or the + key is 
pressed (in symbol shift). 

How do we get the list into the routine? 

The top of the stack contains the return address of the sub-routine, so it 
' points to the code for ‘A’ in the above example. To read it we simply pop it 
off the stack into a suitable register. IFKEY, you will have realised, is 
called as a subroutine but does nof return to the calling program through a 
RET instruction, which requires an extra pop action to match the push 
action of the CALL operation. 


Synopsis 
CLRD clears the display. 
IFKEY waits until one of a preset list of keys is operated. 
WAIT causes a (roughly) + second pause. 
LWAIT _ causes about a one minute pause. 
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Display Output 


The only real way for the Spectrum to communicate with its user is via the 
TV display, so it is very important to be able to do this. I will firstly present 
the necessary calculating routine, followed by a full character output 
program. 

To output to the TV we must first be able to locate a pixel in the display 
buffer. From this routine we go on to write ASCII characters, display text 
strings, display octal numbers and report the contents of the registers. 
Along the way there is an introduction to the idea of ‘global variables’. 


PLOT: locating a pixel in the display buffer 


‘The display file stores the television picture. It is rather curiously laid 
out...’ Spectrum manual Chapter 24 p 164. 

In all these routines the origin of the display is the top lefthand corner of 
the display area. 

The display is divided into three sections, each of eight text lines (64 lines 
of pixels). There are 256 pixels per row — 32 bytes hold the data for 1 row, a 
bit set is an ink dot. The next 32 bytes after those for row 0 hold the data for 
row 8, and the next 32 byte block holds the data for row 16 and so on for the 
first third of the screen (see Figure 7.1a). 

From this we can deduce that a horizontal position (or x coordinate) 
specifies a single bit in one of the 256 bits of a 32 byte block. 

Stage 1 is then to take the x value in one byte and then use the three least 
significant bits to point to a bit in some byte. The remaining five most 
significant bits specify which byte in the 32 byte block is involved. 

Stage 2 is to determine which of the 192 blocks of 32 bytes is involved. 
This must be deducted from the vertical position (or y coordinate). From 
Figure 7.1a we see that: 


Row 0 uses block 0 
Row 1 uses block 8 
Row 2 uses block 16 etc. 


This may not give much inspiration, written like this, but remember that 
we are dealing with a computer and if we think in binary or octal we may be 
better off. 
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Figure 7.1a 


8 SCREEN LINES 
1 TEXT LINE 


O 
(ae el 
GARE ee 
it GR eae 
1. Ss ae aA 
: 3S eae 
| 
TELEVISION SCREEN 


| 
ea st ll i a rick 


192 LINES 


DISPLAY MEMORY 
52 BYTE BLOCKS 


192 


° 
N 


Chapter 7 Display Output 


Figure 7.1b 
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Listing 7.1 
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O795 
OBA 


oOBas 
O814d 
8815 
OB820 


OB25 
OB20 
O825 


O840 
OB45 
O850 
O8SS 
08460 
0865 


O87 a 
0875 
O8Bo 
o8ss 
OBI 
OB95 
OFOO 
O9oO 
O91LO 


OFLS 


O920 


0925 
O9SG 


O9SS 
O94G 
0945 
8950 
0955 
O94O 
O965 
O970 


PLOT 


FLE 
FLA 


FUSH BC 
FUSH DE 
Le At 
AND 7 
ADD 1 
LD E,A 
SRL oC 
SRL oC 
SRL oC 
LD A,B 
AND 56 
SLA A 
SLA A 
oR Cc 
PD. yA 
LD A,B 
AND 7 
Lp (A 
LD A,B 
AND 192 
SRL A 
SRL A 
SRL A 
ADD D 
ADD 64 
LD B,A 
FUSH BC 
FOP HL 
LD #B,E 
LD 4,128 
JR PLA 
SRL A 
DINZ PLE 
FOF DE 
FOP BC 
RET 
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Write down the mapping of Figure 7.1a in octal: 


Row 00 uses block 00 
Row 01 uses block 10 
Row 02 uses block 20 
Row 10 uses block 01 
Row 11 uses block 11 
Row 20 uses block 02 
Row 21 uses block 12 


and light dawns! < 

For the 64 rows of each section, all we have to do is swap the two least 
significant octal digits of the row number (which is the y coordinate) to get 
the 32 byte block number of the section. The remaining two bits of the row 
number must then be 00, 01 or 10 to select which of the three sections we 
want. (11 is an illegal value.) 

Now that we know what we want to do we can draw (Figure 7.1b) a bit 
manipulation diagram. From here the coding is more or less 
straightforward, but note that it is all done in registers. Where a routine is 
to be used frequently memory access operations are to be avoided as they 


_ take half as long again as register access operations. Later on, in writing 
_ characters, this routine will be called eight times per character or 6144 


times for a full screen. 
Now for the formalities and the program description: 


‘ Routine PLOT 


_ Entry Conditions x position in C register 
y position in B register 


Exit Conditions BC asat entry 
DE as at entry 
HL address of display buffer byte 
A one set bit corresponds to the bit in the byte 
addressed by HL which refers to the BC defined pixel 


Note 

1 The target bit in the display buffer is only indicated. 

_ 2 Since the program is ‘drop through’ (except for the A register shift), 
there is no flow diagram. 


The above is an example of the documentation I mentioned previously. 
Now for the program description. 
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SECTION DESCRIPTION 

a Save registers. 

b Mask out the bit number bits, add 1 and save the count in the E 
register (see (h) below for the reason for this addition). 

c Shift the contents of the C register three bits right (this forms 
the index within a 32 byte block). 

d Part 1 of the octal swap; (56 decimal=70 octal) move the 


contents of B into A, mask with 56, move two places left and 
place these three bits in the MS 3 bits of the C register. (Along 
with the five bits which point to the byte within the block.) 

e Part 2 of the octal swap; extract the LS 3 bits from the B register 
and store them in D. 192 decimal is 128 + 64 or the MS 2 bits of a 
byte, extract these bits from the B register (they point to which 
section is needed), move them right three places and add them 
to the 3 bits in the D register. 

f The display buffer starts at 16384, which is bit 6 (decimal 64) in 
the MS byte of a 2 byte address; add 64 to the total in the A 
register and store the result in B. 


Note: BC is now set up with the required address (on the assumption that 
BC pointed to a valid pixel to start with). There remains the problem of 
setting up the A register. 


g BC is transferred to HL. 

h B is set to the contents of E from stage b. This is one more than 
the count in the LS 3 bits because the decrement of B by the 
DJNZ operation is done before the right shift. 
Bit 7 is set in A and the PLB / PLA instruction pair shift A right 
as long as B is non zero. 
Exit is with A having one bit set in the correct place. 

j Restore BC and DE; A and HL are set up as required. 


Exit 

This is probably the most complicated routine in the whole book. 
Everything which outputs to the display uses it and unless you understand 
exactly how it works other things later on will probably be more difficult. 

The Spectrum system allows the BASIC user to position the head of a 
piece of text by using AT and takes a new line with the start of each new 
PRINT statement. In the next part of the program, where we output 
characters in various forms, the top lefthand corner of each 8 x 8 character 
pixel array is located on the screen by two 1 byte variables, LINE and 
COLM. Their relative positions must not be altered as they are used 
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ther to set up BC for acall on PLOT to determine which display buffer 
yytes are to be loaded. 
To simplify matters, COLM is incremented by 8 and when it overflows 
nd becomes zero LINE is incremented by 8. When LINE points off the 
screen it is set to zero and display begins again at the top lefthand corner of 
he screen. The routine NPAGE sets both to zero and calls the display 
uffer clear routine CLRD. 


Listing 7.2(1) 


i775 PRIN : AF 

0980 BC 

0985 , DE 

0990 HL. 

9955 32 

L000 M,PXL 
1005 96 

1010 PY PXL 
1015 96 

1020 AF 

1025 BG y (COL.M) 
1030 PROT 
1035 DE, HL 
1040 MO > 

1045 L4H 

1050 H,o 

1055 HL. , HL. 
1060 HL. , HL. 
1065 HL. , HL. 
1070 BC,15616 
1075 HL, BC 
1080 B,8 

1085 A, (HL) 
1090 Hi. 

1095 DE, HL 
1100 (HL) A 
1105 H 

1110 DE, HL. 
1115 RERT 
1120 A, (COLM) 
p25 8 
1130 (COLM) ,A 
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1135 JR NZ,PXL 
1140 LD A, (LINE) 
1145 ADD 8g 

1150 LD (LINE) ,A 
1155 ADD 644 

1160 JR NZ,PXL. 
1165 LD A,O 

1170 LD (COLM) ,A 
1175 LD (LINE) ,A 
1180 FPXL POF HL 

1185 FOF DE 

1190 FOP BC 

1195 FOF AF 

1200 RET 


1205 COLM NOF 
12190 LINE NOF 


Listing 7.2(2) 

1295 NFAGE CALL CLRD 
1400 FLUSH AF 

1405 L.D A, 

1410 LD (LINE) ,A 
1415 L.D (COLM) ,A 
1420 FOF AF 

1425 RET 

PRIN 


To display a single character at the location defined by LINE and COLM; 
also to set LINE and COLM to point to the next character position. 

This routine uses the Spectrum ROM character table of pixel bit 
patterns, at 8 bytes per character for all the ASCII codes from 32 to 127 
inclusive. They start at 15616 in ROM and each 8 byte block is set up along 
the lines indicated in Chapter 14 of the Spectrum manual. 

The requirement in printing a character is to load into the display store 
the appropriate eight bytes and advance the LINE / COLM pointer(s) to be 
ready for the next character. 


Commentary 

This is acutely dependent on the LINE/COLM pointer indicating a 
character cell not crossing byte or display segment boundaries. I see no 
reason for complicating the problem, but see Chapter 8 for how to deal 
with the general problem. 
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owchart 7.1 


if PRIN 


A=At%6 
STORE AF ON STACK 
LOAD BC WITH LINE + COLM 


FIND DISPLAY 
BUFFER ADDRESS 


A STORE BYTE ADDR. IN DE 


HL=A x~+ 
HL=HL#*8 2xt 
HL» HI+ HEAD OF ROM 4% 

TABLE DATA 


4x= 6x 


5 L) BYTE OF BITS FROM ROM 

E DE- HL 
=A WRITE. Row INTO DISPLAY BUFFER 
H=H+1 ON DISPLAY BUFFER ADDRESS 


EXCHANGE DE- HL (Move oe NEXT BLOCK 
B= B-1 BYTES — SEE PLOT) 


y 
4, 
4 
“$ 
“f 
Z 
4, 
‘sf 


VAAL SAAS CS 


RESTORE REGISTERS 


PRIN 


i 
i 
il 
i 
i} 

| 
i} 
tt 
i 
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The routine is entered with the ASCII character code in the A register 
and it is first tested for ‘printability’. Non-printable characters are 
omitted, not replaced by blanks. 32 is effectively subtracted from the 
ASCII code, to give a position pointer to the bytes in the ROM, and A 
stored on the stack. PLOT is now used to determine the address of the 
display buffer byte to be used for the first row of pixels. LINE and COLM, 
stored as adjacent bytes, are collected together by the LD BC,. . operation. 

From PLOT the byte address is stored in DE and the character code 
recovered, multiplied by 8 (8 bytes per character) and added to the head 
address of the ROM data table to point to the required bytes. This is the 
address to change if you want to use your own character definition bytes. 

B is set to 8 to count the 8 bytes to be transferred from the ROM. That 
byte is transferred to the display buffer and the display buffer pointer 
incremented by 256 to point to the 32 byte block where the next byte is to be 
placed. This is done by incrementing the H register of the HL pair when it 
contains the appropriate data. The transfer loop at RPRT keeps its two 
pointers in HL and DE, exchanging them as needed. It starts off with HL 
pointing to the ROM and DE to the display buffer. 

After the character has been written to the buffer COLM is incremented 
by 8 (8 pixels maketh one character row) to point to the next character in 
the line. If the count has gone over the top and become 0 LINE is 
incremented by 8 (8 pixel rows maketh one character) and the result tested 
against 192 for ‘beyond bottom of screen’. If at the bottom both LINE and 
COLM are reset to zero. The routine exits after restoring registers, except 
the A, at PXL. 

This routine will not work properly if either LINE or COLM come to 
contain any value which is not an exact multiple of 8. A first exercise for 
you is to modify it to ensure that they do stay as exact multiples of 8. 


PTEX 


Printing text, which is just a question of feeding PRIN with a sequence of 
characters, is achieved by arranging the text to be printed in the bytes 
immediately following the call of the routine and having it terminated with 
a zero byte. This works perfectly well with fixed length text, composed or 
allocated at assembly time, but you will need to produce a modified version 
which deals with text held somewhere else at a known address. I strongly 
advise you, however, to mark the end of such text with a zero byte as it is 
non-printable and easily tested for. 

We saw in IFKEY how to use the subroutine return address from the top 
of the stack to get at data immediately following the call of a subroutine. 
We do the same thing here to get at the first, and subsequent, characters of 
the string. At PXB, with HL pointing to a byte, it is loaded into the A 
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2700 SRHLS 


SRL. 
SRL 
RET 
SET 
RET 
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CALL. SRHL# 
CALL SRHL# 
CALL SRHL 


RET 
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Flowchart 7.2 


HAG OL GAILNIdd 
SSaudadv QL dWAL 


YSWaVW LXSL 40 GNA 


TH AG OL CALNIOd 
YWALIVYVH? HUM WW dvoT 


WIWLS WOYs TH GvOT 


xatLd 


TH -LNAWSYONI 
TH ANOLSAY 


MIVLS 
NO IH SOLS 
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egister and compared with zero; if it is the end of text marker byte then HL 
is pointing to a NOP instruction as well and the JP (HL) instruction 
transfers control out of the routine and back to the main program; 
otherwise, at PXA, A contains an ASCII character to be displayed by 
PRIN. While PRIN runs the text pointer is saved on the stack so that it can 
be recovered and incremented. Return is then made to PXB to collect the 
‘next character or the end marker. 

_ Now come two primitive routines for doing a double byte, 16 bit, right 
shift. There is a much better, more elegant and faster way of shifting right. 


SRHL 


The two SRL operations shift each register right 1 bit place, the second, on 
the more significant byte, will set the carry flag if a bit is ‘lost’ on the 
bottom and unset the flag if no bit was lost. The RET NC exits from the 
routine when no correction has to be made to the L register, otherwise the 
"Jost bit is replaced in the MS bit of the L register by the SET 7,L operation. 


_ RHL3 

This performs three right shift operations together, so dividing the 

contents of the HL register pair by 8 which is just what is required when 
printing octal numbers as described in PRT8. 


ae 


PRT8 


Now we can print text, what about numbers? Well, there are all sorts of 
complicated routines that you can read about elsewhere. This will just print 
a 16 bit binary number, in HL, as a 6 digit octal number, no frills, no sign, 
just something simple so that we can have a method of debugging 
programs later on. 

There are two tricks here: 


1 The ASCII characters for digits are a sequential set from 48 (decimal) 
_ onwards, so the required octal character is obtained by adding 48 to the 3 
binary bits of the octal value in question. 


2 Use the ready-built PTEX routine to do the output and overwrite what 
was output last time. 


On entry the registers are all saved on the stack and DE pointed to the 
byte where the LS digit of the output is to be loaded for printing by PTEX. 
Bis set to 6 as there are only six bytes to be produced. At PRU3 the three 
least significant bits of HL are obtained by masking and the character code 
for the value calculated by the addition of 48. This is stored in the location 
indicated by DE, DE is decremented and HL shifted right three bits to 
reveal the next octal group if B does not go to zero. If B is zero all six bytes 
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Listing 7.4(1) 
i 
a 1430 PRTS FUSH AF 
1435 FUSH BC 
a 1440 FUSH DE 
a 1445 PUSH HL. 
id 1450 LD DEG REZ 1 
i 1455 LD B,6 
i= 1466 FPRUS LD A, 
Ik 1465 AND 7 
} 1470 ADD 48 
i 14735 LD (DE) ,A 
dl 1480 DEC 2 DE 
q 1485 CALL RHLS$ 
q 1490 DINZ PRUS 
1495 CALL FTEX 
1500 DEFM "“cdefgh" 
1505 FSZ1 DEER 
1516 NOF 
Add ot Be Beis 
1520 ROP =.DE 
tG25 FOR SBC 
T3509 POP AF 
1535 RET 
Listing 7.4(2) 


a 5440 PRTBW PUSH HL 

i 5445 FUSH AF 

ii 5450 PUSH DE 

1a 54555 FUSH BC 

i 5460 CALL FRTS 

4 5465 CALL. [FKEY 

14 5470 DEFB "m" 

hi S475 JF FRE X 

me. 5480 NOF 

t) 5485 FREWX FOF BC 

4 5490 POF DE 

fi 5495 FOF AF 

1 5500 POF HL” 
iq 5505 RET. 
i 
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Flowchart 7.3 


PRT 8 


SAVE ALL REGISTERS 

SET DETO POINT TO THE 

LS DIGIT CHARACTER 

LOAD BTO COUNT 6 OCTAL CHARACTERS 


LOAD A WITH 3 LS BITS OF L 
ADD CODE FOR 

STORE ASCII PangsER IN (DE) 

SHIFT HL ay ie 3 BITS 


RESTORE ALL REGISTERS 


sf 


on 
i 


ee 


f 
i 
ql 
if 
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have been loaded on top of hgfedc in the listing, P8Z1 is a pair of spaces to 
terminate the displayed 6 characters output by the call of PTEX after 
which all the registers are restored to their entry values and the routine 
exits. 

PRTS8 can thus be inserted anywhere in a program when a check is 
required on the contents of HL. 


RPORT 
While debugging programs it is often necessary to be able to display the 
values of all the registers, so the next routine does exactly that, together 
with the return address using PRT8. Since the program is so 
straightforward there is no flow diagram. 

There are three points to be noticed: 


1 The stack pointer value, indicated by $= can indicate if the program is 
‘running away’ because of unmatched POPs and PUSHs. 


2 The CALL RPORT return address, indicated by +, allows several 
outputs from different calls to be distinguished. 


3 The messy way data is passed into HL to print the return address. There 
is a better, more elegant way by computing the instruction, as is 
demonstrated later, in MOVER and VAR$1 for example. 


Listing 7.5 

1540 RPORT LD Crs) or 
1545 PUSH AF 

155° FUSH BC 

L555 FUSH DE 

1560 PUSH Al 

iSé6é5 L.D CHL) HL 
1570 L.D CDES ), DE 
1575 L.D (BC#) , BC 
1580 FUSH AF 

1585 PoP at. 

1590 LD (AF #) ,HL 
1595 CALL. FTEX 
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(14600 
1605 
1610 
1615 
16206 
1625 
1630 
1635 
1640 
1645 
1650 
FOOD 
1440 

—61465 
1676 

~614675 

«1480 

-~61485 

61696 

1697. 

e 1700 
1705 
1710 
1715 
1720 
a7 2 
1730 
L730 
1740 
1745 

1750 
Thabo) 
1740 
1765 
1770 
Bais 
1780 
1785 
1790 
1795 AFS 
1860 HLS 

A805 DEF 
18190 BCS 
1815 SPs 


u AP = uw 


HL., (AF#) 
FRTS 
PTEX 

u BC= uw 


HL, (BC#) 
PRTS 
FTEX 

" HL= u 


HL, (HL) 
PRTS 
FtEX 

mW DE= thi 


HL, (DE#) 
FRTS 
FTEX 
Wee 


HL, (SP) 
FRTS 
PTEX 
" f= uw 


HL., (SP#) 
E, (HL) 
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Figure 7.2 
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Map$ 
Now let us put some of the bricks together for something useful — a 
routine for displaying the free space in memory. 

We have available 6144 bytes of display buffer which contain 48k of 
pixels so we can map each RAM byte to a pixel (we ignore the ROM) by 
setting the pixel to black ink if the byte is neither space, in ASCII, nor 
blank, otherwise the pixel is left paper coloured. 


Commentary 


The calls of NPAGE and PTEX clear the display and set up the output 
description in the top two lines; the top three text lines, or 24 rows of pixels 
map to the display buffer and we know what is there so I don’t map that 
either. 

From labels NXF1 to NXF3 the routine is setting up the attributes area 
so that each line of 8 rows of pixels is a different colour from its 
neighbours. Each row, remember, covers 8*256 = 2048 bytes of RAM and 
even rough location is impossible if the screen is all the same colour. 

At NXF3 HL is set to the address of the head of RAM and BC, initialised 
to point to the first address beyond the end of the display buffer, and 
results in the sum HL + BC being the address of the byte to be currently 
tested. If this sum runs beyond 16 bits to zero the carry flag will be set and 
the routine exits on the RET C after all the RAM has been examined. The 
byte addressed by the sum, in HL, is loaded into the A register and tested 
for 0/32, in either case of equality the PLOT routine is skipped and the 
pixel left as paper colour. 

Since the byte count is from the head of RAM in BC the lower byte can 
specify a pixel x position and the higher byte the pixel row. It is of course 
the purest happenstance that this is the way that PLOT requires its input to 
be specified. 

Setting the ink pixel is just ORing in the bit in the A register, after the call 
of PLOT, with the address specified by HL. The program then returns to 
NXF with an increment BC to test the next byte. 


Synopsis 

PLOT performs the same function as the Spectrum plot function, it is the 
foundation of all display output. It forms the basis of the animation 
routine of Chapter 8 and the drawing program of Chapter 13. 


PRIN displays a character, ASCII code in the A register, at the next 
available character position. 


NPAGE clears the screen and sets PRIN to start at the beginning of line 
one. 
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Flowchart 7.4 


MAP$ 


[[ weame: || cesan scnzes 
[prex |] tme orpispay 


HL= HEAD ADDRESS OF ATTRIBUTES a 4 
C=24 24 LINES OF 32 CHARACTERS 


SET UP ATTRIBUTES 
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DE = ATTRIBUTE CODE LIST HEAD ADDRESS 
A=ATIRIBUTE POINTED TO BY DE 


DE=DE+1 (NEXT ATTRIBUTE) 
B=32 (32 CHARACTERS/LNE) 


BC= 614-4 (SKIP DISPLAY 
BUFFER) 


163584 (SKIP ROM 
HL+BC . . 


HL 
HL 


— ae EE 


“HeMony BYTE 


LEAVE AS PAPER 
COLOUR. IF BYTE 
1S srace OR ASCII 
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1820 
1825 
1830 


1835 
1840 
1845 
1850 
(1855 
1860 
~61865 
1870 
1975 
1880 
1885 
~—61890 
~=1895 
61900 
1905 
1910 
1915 
1920 
e250 
1930 
1935 
1940 
1945 
1950 
1955 
1940 
19465 
1970 
7S 
1980 
Regs he 
1990 
1995 
2000 
2005 
2010 


Listing 7.6 


MAF 


NXF 1 
NXF2 


NXFO 


NXFS 


NXF4 


List 


CALL 
CALL. 
DEFM 


NF AGE 
Poe 
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" STORE MAF FROM 22528 TO 


HL, 22528 
C,24 

DE ,LIST 
A, (DE) 


HL. , 16384 
HL, BC 

c 

BC 

A, (HL) 

(8) 

Z,NXF4 


‘ 
i 
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PTEX uses PRIN to display the text following its call (the text must end 
with a zero value byte). 


PRT8 uses PRIN to display the contents of HL as an octal number. 
PRT8W uses PRTS8 with a wait for the ‘‘m’’ key to be pressed. 
RPORT displays the contents of the registers (not [IX and IY). 


MAP3$ displays memory occupation. 


CHAPTER 8 
Animation 


- GCELL 


_ The aim and object of this routine is to display rapidly a sequence of images 

at a moveable point on the screen. These images or patterns are drawn ina 

box or cell. The larger the cell, of up to 2040 pixels, the longer the routine 

takes. The BASIC interface is just about as complex as can be handled 

_ without designing a fundamentally new, and more general, technique: see 
Chapter 9. 


Interface 


_ The user sets bytes 23675/6 (UDG) to the address of the first byte of a block 

of data, defined below, which the routine will use. There may be several 
‘such blocks, switching amongst them is done by changing the contents of 
UDG. 


BYTE DESCRIPTION 
0 cell horizontal position x 
cell vertical position y 
control flags and next frame no. * 
BCR no. of bits per cell row 1 — 255 
BCC no. of bits per cell column 1 — 255 
WPC no. of works per cell 1 — 255 
frame sequence control bytes; the LS 4 bits of byte 2 to 
one of these 15 bytes; the LS 4 bits of this byte define 
which cell is 
20 to be displayed 
21 ; set to 0 
22 first byte of cell 1 data. There are WPC bytes in this and 
the other cells 
22 + WPC first byte of cell 2 data 
22+2.WPC first byte of cell 3 data 


NDNnunkb won 


and so on for as many cells, up to 15, as are needed. 
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Control flags and next frame no. — byte 2 


BIT NO. DESCRIPTION 
7 MS bit: if set the routine exits doing nothing 
6 set by the routine if any part of the currently displayed cell 


is outside the allowable display area. This bit should be 
monitored by the user program 

not used 

if zero the routine exits 

If non zero the contents are used to point to a frame 
sequence control byte which identifies the next cell to be 
displayed. (Add 5 to the value and the result is 6 to 20; this 
is the number of a byte, relative to the head of the block, 
which contains the cell identifier). The routine 
increments this pointer or resets it to 1 after the end of the 
sequence list is met, as recognised by a zero entry. This 
can always be overwritten by the user rewriting byte 
(UDG) + 2 


wn 
| 
of 


Cell data 


Each row of pixels in a graphics cell starts at the MS bit in the first of a 
sequence of bytes. There are BCR/8 bytes in this sequence, and surplus bits 
are ignored. There are BCC sequences, one for each row of pixels in the 
cell. Each set bit generates an inked pixel but remember that the attributes 
area must be set up as a separate exercise. 


Description of GCELL 


SP is stored in PANIC so the stack can be reset and a dignified exit made if 
the routine attempts to write beyond the allowable display buffer area. The 
first 21 bytes of the control data is copied into the routine and TM1 set to 
the address of the first graphics cell. Byte 2, the flag byte, is now tested and 
the routine exits if ‘switch off’ or no cell is specified, otherwise the last four 
bits specify which sequence table entry contains the required cell number. 
LOA to L2 and DJNZ operation pick up this cell number and set CELLZ 
with the head address of the cell data. 

At L4A—L4 the next sequence table pointer is calculated and stored 
back in the interface table byte 2 ready for use at the next call of the routine. 
FADDR is set up with the address of this byte for use by SEBIT if need be. 
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Flowchart 8.1 

GCELL 

STORE SP FOR FAILURE EXIT 
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NUM 
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CELLZ = HL (HEAD OF SUBJECTCELL 
A= NEXT SEQUENCE CELL Y 


= WES END OF 
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IN PROGRAM (FLAG BYTE) 


FADDR = FLAG BYTE ADDRESS 


A 
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co) NUMBER OF CELL ROWS 
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FOR FIRST BYTE OF THIS ROWS DATA 
A= HORIZONTAL PIXEL POSITION 


A=A2-g (REQUIRED RIGHT SHIFT OF CELL DATA 
BC= DATA ROW HEAD ADDRESS 


| SEBIT — 1 ROW OF CELL DATA TO DISPLAY BUFFER 


CELLZ = CELLZ + WPR POINT TO START OF NEXT ROW 
INCREMENT DISPLAY ROW 
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Listing 8.1 


2015 GCELL LD (FANIC) ,SP 
2020 UDG 23675 
(2025 HL., (UDG) 
2030 DE, XY 
2035 BC ,CELLZ—-XY-1 
3040 

2045 (TM1) ¥HL 
2050 A, (FLAG) 
2055 7,8 

2060 : NZ 

2065 15 

2070 (FLAG) ,A 
2075 1 

2080 M 

2085 A, (BCR) 
2090 

2095 

2100 

2105 (WFR) A 
2110 A, (BCR) 
2115 7 

2120 : Z,LOA 
2125 A, (WER) 
p21 30 1 

2135 (WER) 4A 
(2140 HL. ,FSEQ—1 
2145 A, (FLAG) 
2150 BLO 

2155 C,A 

2140 HL, BC 
2165 B, (HL) 
2170 (TM2) ,HL 
12175 A, (WPC) 
(2180 E,A 

2185 D,o 

2190 HL, (TM1) 
2195 L2 HL. , DE 
2200 te. 

2205 a) 

2210 HL. , DE 
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Zero 
3930 


ae a a 


2225 
2230 
2235 
2240 
2245 
2250 
2255 
2260 
2265 
2270 
2275 
2280 
2285 
2290 
2295 
S00 
2305 
2310 
2415 
2320 
23520 
23350 
2335 
2340 
2345 
2350 
2355 
2360 
2365 
2579 
2375 
2280 
2385 
2390 
2395 
2400 
2405 


L4A LD 


L4 _D 
XX LD 


FANIC DEFW 


WPC DEFE 

FSEQ DEFM 
NOF 

CELLZ <“DEFW 


2410 WER DEFW 
2415 TML DEFW 
2420 TM2 DEFW 
2425 FADDR DEFW 
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(CELLZ) ,HL 
HL, (TM2) 
HL. 


(HL) A 
(FADDR) ,HL 
A, (BCC) 

1 

M 

(BCC) ,A 
BC, (XY) 
FLOT 

A, (XY) 

7 

BC, (CELLZ) 
SEBIT 

HL, (CELLZ) 
BC, (WER) 
HL. , BC 
(CELLZ) HL 
A, (XY+1) 

1 

(XY+1),A 
LXX 

Q 

QO 

QO 

i) 

ie) 

Oo 
"cCD.N.sLaine 1983" 
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Cell plotting (LX X onwards) 


On entry XY holds the position of the top lefthand corner of the cell in 
PLOT required format, the other rows are defined by incrementing the y 
part of XY. BCC is used as a counter of the number of rows to be output 
_and the routine exits when BCC has been decremented below zero. 
PLOT determines the display buffer load byte address and bit number 
- for the head of the current row of pixels which is pointed to by CELLZ, and 
SEBIT plots the row of pixels; CELLZ is then incremented to point to the 
head of the next row of pixels and the loop repeated. 


SEBIT 
This routine plots or unplots pixels in the display buffer according to how 
they are set or unset in the cell row. Separate pointers are maintained to 
step through both sets of bytes. 
 Atentry to DNB HL points into the display buffer and DS points to the 
bit to be set/unset; CELLZ points into the cell data and TS is the bit 
- number of the cell byte; WC is a count of bits/pixels per cell row — the 
routine loops BCR times. 

TST is a computed bit test instruction to test the TS bit in the cell byte, 
_ according to how the bit is to be set/unset. So SET or RES instructions are 
computed and excuted at DO to set or unset the required bit in the display 
buffer. 

Having dealt with one pixel the pointers are incremented; if either bit 
pointer is negative it is reset to 7 and the corresponding byte pointer is 
incremented. If the display buffer pointer, HL, points into the last pixel 
_ row then, since to simplify matters this is forbidden, the flag byte has bit 6 
set and there is a PANIC escape. 


Note: this uses computed instructions: how will your assembler deal with 
them? 


64 + 7 generates the BIT ?,A instruction 
128 + 7 generates the RES ?,A instruction 
192 + 7 generates the SET ?,A instruction 


_ Synopsis 


GCELL, which uses PLOT, enables you to do complex animation. 
Chapter 13 will let you set up blocks of colour. Later on there is a routine to 
_ move the blocks around, or so it will appear. 
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Flowchart 8.2 
SEBIT 
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‘ DOB 76 g 
MOVE COMPUTED 2" BYTE 
A= DISPLAY BUFFER BYTE 
2 POINTED TO BY HL 
fF TE SET/RES (AS COMPUTED) 
i OY ea RESTORE BYTE TO DISPLAY BUFFER 
MOVETO HL=HL+1 ean 


NEXT CLEAR Cy FLAG 
moat gid DE=TEST LIMIT 


YES 


SET FLAG BIT 6 
RESET SP POINTER 
PANIC ESCAPE 
ae 
(THE NEXT BYTE ISIN ROW 141 MaA-1 


=THE BOTTOM ROW OF DISPLAY 
PIXELS IS NOT USED) 


MOVE TO NEXT 
CELL BYTE 


ZA SET TS FOR NEXT CELL BYTE TEST 
A =W WORDS PER CELL (COPY) 


NO YES THIS ROW ALL DONE 
DO NEXT BIT 
6s) Wc=A 


“| 


TZ 
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Figure 8.2 
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Listing 8.2 


2430 
2435 
2440 
2445 
2450 
2455 
2460 
2465 
2470 
2475 
2480 
2485 
2490 
2495 
2500 
2505 
2510 
2515 
2520 
2525 


Sa30 


2525 
eo4Q 
2045 
Sago 
Soe 
2560 
2565 
2a7Q 
2a7g 
2aB0 
2085 
eo9) 
S595 
24600 
2605 
2610 
2615 


2680 


SEBLT 


DNB 


TST 


SETE 


DOB 


ba 


A, (BCR) 
(WO) ,A 

a, (TS) 

A 

A 

aA 

64+7 
(TST+1),40 
A, (BC) 


A, (DS) 


19247 
(DO+1) ,A 
A, (HL) 
O,A 

(HL) 4A 
A, (DS) 

A 

ey, Jha 

Hi. 

a 

DE, 22496 
HL. , DE 
HL. , DE 

M, JMX 
HL., (FADDR) 


2655 
2640 
2645 
2650 
26955 
2660 
2665 
2670) 
2675 
2680 
2685 
2690 
2695 
2700 
2705 
2710 
2/15 
2720 
of7eg 
2730 
27 


2740 


2745 


JMX 
JMA 


JME 


DS 
TS 
we 


L.D A, CHL) 


OR 64 
LD (HL) ,A 

LD HL, (PANIC) 
LD SFYHL 

RET 

kh Ag? 


LD (DS),A 
Ds, “Ay Crs) 


DEC A 
JF FY, JMB 
CD “ALF 
INC BC 


LD (TS),A 
LD A, (wo) 


DEC A 

RET ™M 

RET 2Z 

LD (WO),A 
JR DNB 
DEFB © 

DEFER © 

DEFB Oo 
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CHAPTER 9 
Error Handling and Parameter Name 
Passing 


Error return handling 


The notes on the stack (Chapter 3) mention a method of escape from a 
piece of code if some insoluble or unforeseen condition is encountered (see 
also Chapter 8 and the use of PANIC). In such an event it is very useful to 
be able to output some indication of the problem. 

Machine code seems nearly always to be called by RANDOMISE 
USR... There is no fundamental need to do this; Chapter 26 page 180 of 
the Spectrum manual uses PRINT USR 32500 to print the contents of the 
BC register (as set up by the machine code); if we code such that they always 
exit abnormally with BC O we can call them by: 


IF USR...<> 0THEN GOTO. . .error routine 
or, better 


LET errorcode = USR... 
IF errorcode < > 0 THEN GOTO... 


since we can design the non zero value to have some special significance. 
All these IF... <> 0 THEN GOTO... are unslightly and (worse still) 
are in BASIC. Look at the variables NEWPPC and NSPPC in Chapter 25 
page 174 of the Spectrum manual. 
NSPPC tells us exactly what to do. We design the BASIC part of our 
program such that some line, say 2, is the line to be jumped to in an error 
condition. Our error exit must then contain: 


LD HL,2 

LD (23618), HL 
LDA,1 

LD (23620),A 


which pokes NEWPCC with 2 and NSPCC with 1. Lo and behold, we 
arrive at line 2 in BASIC. 
We now undertake to call our routine by: 


LET errorcode = USR... 
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Figure 9.1 
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LONG NAME CODE 


PETE [ep Po] ase e 
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ASCIL @-60n 


es 

2 

SF 
CHARACTERISTIC 

2 

—— 
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and continue normally with the next statement. With any error exit we 
arrive at line 2 and errorcode contains the value of BC when the exit was 
made. Strange as it seems, the assignment of BC to errorcode is made 
regardless of how the exit is made. 

There is just one small snag on the horizon. We can use BC as a means of 
passing information out of the machine back into the BASIC world, and it 
would be a pity to waste this facility for error routines. After all, good 
programs like ours do not meet error conditions (!) Can we get the error 
information out some other way? 

Again the Spectrum manual has the answers, well hidden away in the 
depths of Chapters 24 & 25. It is a somewhat roundabout path but I can 
promise some primroses by the way. 


1 23627/8 — VARS contains the address of the head of the variables 
tables in the BASIC program. 

2 Pages 166—170 shows how these variables and their names are 
organised. 


If the FIRST executed line in the BASIC is: 
0001 LET ERROR = 0: GOTO... 


then the head of the variables area will be as Figure 9.1 and the error 
routine in the machine code program can locate bytes 5—9 and insert values 
as required into the variable ‘error’. The key here is that the first statement 
in the program forces the first variable to be located at the head of the 
variables area. At any point in the running of a BASIC program the 
sequence of the variables in the variables area will probably depend on the 
way in which that point in the program was reached since entries are made, 
as required by LET ??? =... statements, as they are encountered. 
Our program now looks something like: 


0001 LET error = 0: GOTO 100 


0002 PRINT ‘‘ERROR CONDITION = ”’serror 
0003...... error handling routines... 


0100 REM program proper starts here 
0101 


0150 LET q=USR... 


and q is some useful value generated by the routine and passed back to the 
BASIC program via the BC register. 
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Note now: 


— 


BC only allows you to get a value from code into BASIC. 

2 ‘Error’ can, if you want, be a 5 byte Spectrum floating point number 
of a Spectrum integer value. 

3 We can now communicate between code and one BASIC variable, 
and, by extension, the BASIC program. 

4 Wecould even change the use of ‘error’ and use it as an input variable 

to the machine code. 


We can stop here, or go on to develop a method of passing variable 
names and values (parameters) between the machine code and the 
Spectrum BASIC program. We need to be able to do two things: 


1 Pass variable names to the routine 
2  Givena variable name, we have to find its address in the variables area 
of the BASIC program. 


Let us first formalise how we are going to deal with error conditions. 

On program entry we undertake to ensure that the first BASIC variable 
has a five-character name which will be reserved for passing error codes. 
We further undertake that our error handling routine(s) will start at line 2. 

The machine code routine(s) all commence by storing the current value 
of the stack pointer for the (exclusive) use of the escape mechanism. 

The escape mechanism shall return to the BASIC program the then 
current contents of the DE register pair, into this first BASIC variable, and 
force the return to line 2. 

Entry to the escape mechanism is with DE set to a suitable code value and 
a JP, CALL, or JR operation as seems appropriate. 

The routine is listed in Listing 9.1. ERROR is the stack pointer reset 
value set up at the routine call. 


Listing 9.1(1) 


1215 ERREX Lp HL, (ERROR) 


1220 LD = SFYHL 

1225 LD HL,2 

1230 LD (23618) ,HL 
1235 Go : Aas 

1240 LD (23620) ,A 

1245 LD HL, (23627) 
1250 LD BC.7 

i255 ADD HL,BC 
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1260 
1265 ERADR 
1270 
1275 ERROR 


Listing 9.1(2) 


oOoOos 
OOO 
OoOLS 
OOO 
OOSS 
OOO 
OO85 
OO4 
Oo4s 
oOosG 
OOSS 
OO6O 
QO6S 
OoO7O 
OO73 
OoOBa 
Oog8s 
ONO 
O95 
O100o 
O10 
O1190 
O115 
O120 
QO125 
O130 
OL35 
O1L40 
O14 
O1so0 
O1S5 
O1460 
O165 
OL170 
O175 


LD 
L.D 
RET 
DEFW 
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(ERADR+2) ,HL 
(ERADR+2) ,DE 


oO 


40000 
(ERROR) , SF 


AF 


AF 


SORTF 
TRAPS 
(ERROR) , SF 
AF 


8] 
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OL1B0 
O185 
O190 
O195 
O2OO 


O205 


0245 
O250 
O255 
0260 
0265 
O27Q0 
0275 
O2BO 
0285 
O296 
0295 
OS00 
O305 
OSLO 
OF15 


OSLO 


O40 
O245 
OFS50 
25S 
O60 
O365 
OS70 
O375 
OSBO 
O385 
OS9O 


O39S 
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FUSH 
FUSH 
FUSH 
FUSH 
CALL 
JF 


BC 

DE 

HL. 

Ix 

GCELL 
TRAFS 
(ERROR) ,SP 
AF 


(ERROR) , SF 


IVERT 
TRAPS 
(ERROR?) , SF 
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O40 CALL DRAWA 

O4os JF TRAF# 

O410 LD (ERROR) , SF 
O415 FUSH AF 

O420 FUSH BC 

C435 FUSH DE 

O430 PUSH HL 

OAS FUSH IX 

O4AO CALL DEMO 

O4gs JF TRAF' € 

O450 LD (ERROR) , SF 
0455 FUSH AF 

9460 FUSH BC 

0465 FUSH DE 

O470 FUSH HL. 

O475 FUSH IX 

O4BO CALL DEMO? 

o485 JF TRAFE 


0490 TRAF# FOF Ix 
O4935 TRAGQE FOF HL 
O500 TRAR# FOF DE 
O505 TRAS# FOF BC 
OS10 TRAT# FOF AF 
O3LS RET 


Passing variable names (parameters) 


Chapter 25 page 174 of the Spectrum manual holds an answer to the 
problem. NXTLIN (location 23637/8) contains the head address of the 
next line of the BASIC program ie the one after the one which contains the 
LET... = USR... statement. We might put a list of parameters in this 
next line, hidden from the BASIC system by a REM statement. 

A code call with parameters would then look like: 


0175 LET y= USR 12345 
0176 REM a, b: REM aand bare parameters of USR 12345. 


Chapter 24 page 166 tells us how to get at the names. NXTLIN points to 
the MS byte of the line number so (NXTLIN) + 4 is the address of the first 
character of the text of that line; we step down the line looking for the REM 
token (= 234) and then we start looking for the variable name which we will 
specify to end in a comma, colon or an ENTER token. Spaces will be 
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ignored and integers will be detected as they commence with a digit... 


STOP !!! 


It is very easy to get carried away when designing a piece of program; the 
specification becomes bigger and better, all singing and dancing, and much 
harder to debug; so much so that the program, which started as a good 
idea, becomes: a bilious nightmare and is eventually abandoned in a 
mixture of disgust and despair. 

Let us abandon, for the time being, passing numerical values and 
multicharacter variable names, and restrict ourselves to passing a limited 
number of single letter variables (which may be simple variables, strings or 
arrays). We can always go and complicate matters later on. 

Flowchart 9.1 is a reproduction of the original flow diagram; Flowchart 
9.2 is the final version which ties up with Listing 9.2. The box VAR$1 is 
another routine which searches the variables area looking for names 
(Flowchart 9.3). It returns either A=0 end of data, or HL holding the 
address of the head of the variable name and A = first 3 (code) bits of that 
name: see below for the details. 

The routine does not do exactly what it might have been thought it would 
do. The letters, brackets and $ can be in any order and the effective variable 
identifier is the last letter. The REM statement must be terminated bya 
colon or ENTER token. It is left to you, the reader, as a simple exercise to 
remedy these defects if you want to. 


Documentation 
Entry conditions none 
Exit conditions All registers lost 


PARMO-PARM6 are the addresses of the first 
characters of up to seven variable names in the 
BASIC variables area. 0 indicates that no 
parameter is present 


Note: The calling routine must verify that the type of the received variable 
is correct and extract/load the appropriate bytes. 


PCALL 


The number of parameters to be handled, PARMO, PARMI,... is 
calculated at assembly time and PEND, their count + 1 , is set up on entry. 
The right shift allows for two bytes of storage for each PARM location. 
For more parameters just add 2 byte storage as required between PARM6 
and PEND; the LDIR operation will clear everything on entry. Remember, 
the PARM list contains the ADDRESSES of the head of each variable 
name. 
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Flowchart 9.1 


Pro: temseTqco Phz0, B=0, L=¢ 
ve (wxtr)4 2 


Couser Coe 
ian 
iv 
sift AN 
L= A-bok © < 
4 40) © 6-1 


At AL) A a a 
2 4 a3 
a ___ Lied, 


: ERLoL 
oe rae \o ND. bleak Be |B | | 
“ 
4-0 
Fae ee FS13 
| Avee | Fao 


ba yes 
_ ap 
ee {J E0e | 
as 
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Flowchart 9.2a 


PCALL —a 


FIND ogee ae vie NAMED PARAMETERS IN REM STATEMENT 

FOLLOWING USR CA 

ENTRY - NONE 

EXIT - ADDRESSES OF KEADS OF PARAMETER NAMES ARE PLACED IN PARMG, 1 etc. 


oma WORKSPACE + OUTPUT ADDRESS TABLE ALSO F$ AND RB 
ET PARAMETER LIMIT COUNTER = vs OF ALLOWED LIST +1 

er §X =HEAD ADDRESS OF OUTPUT T/ 

SETHL =HEAD OF TEXT IN NEXT UNE 3F BASIC PROGRAM 


ENTRY FROM 
F4,4b 

IEXT CHARACTER OF REM STATEMENT LINE. 

NO YES REMOVE SPACES HERE 


HL = HL+1 
Ph =P6+1 TOTAL CHARACTER COUNT 


No Cron Sis 


256 CHARACTERS 
a a BEEN READ 
TOO MANY) 


L READ UNTIL REM 


REM TOKEN 
HAS BEEN 
READ 


TOKEN IS FOUND 
AFTER REM READ NEXT 


= 


COME HERE FORALL 
CHARACTERS AFTER REM 


A =(HL) A HOLDS NEXT CHARACTER 


F$ MARKS ” $” READ 


END OF 
PARAMETER 


LETTER CODED 1 TO 26 
B- aTos 
NOT LOWER CASE LETTER ria 
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Flowchart 9.2b 


PCALL —b 


ENTER HERE AFTER READING 
THE END OF A PARAMETER ENTRY 


A=BIT6,5 


AHOLDS PARAMETER TYPE CODE AS PER 
"7 aa VARIABLES AREA ENTRY 
A=A0 
A NOW CONTAINS FORM OF PARAMETER 
TO BE LOOKED FOR IN VARIABLES AREA 


A STORE ITINB 
lt) INITIALISE ENTRY FOR VAR$1 


END OF VARIABLES AREA 


A HOLDS FIRST 
NO SUCH PARAMETER ENTRY 


CHARACTER FROM 
VARIABLE NAME. 


YES VARIABLEPOR’ qo 
NO 6-0 
THE REQUESTED PARAMETER 
HAS BEEN FOUND - 
IWS HEAD ADDRESS IS IN HL 
STORE HLIN PARAMETER ADDRESS LIST 
INCREMENT IX—THE LIST POINTER 
DECREM METER COUNT PEND 


YES 


TOO MANY ENTRIES IN 
CLEAR 'F$, RB ‘ST 
RESTORE HL ROM Pz a alas 
(HE Fo! POINTS TO CHARACTER LAST 
READ FROM REM STATEMENT) 


NO YES LAST CHARACTER WAS 
: OR ENTER TOKEN 


F.4,4a COLLECT NEXT CHARACTER 
FROM REM LIST 
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Listing 9.2 


2750 
2755 
2760 
2765 
2770 
2775 
2780 
2785 
2790 
2795 
Z2BOQ 
2805 
=B810 
“915 
2820 
2825 
2830 
2835 
2840 
2845 
=850 
2855 
2860 
28465 
=B70 
2875 
[880 
“885 
2B90 
2895 
2900 
2905 
2910 
2915 
2920 
2925 
2930 
2935 
22740 
2945 
2950 
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FPCALL 
NXTLN 


RR 


RRR 


RST 


RSET 


RT 


RV 


HL, 
23637 
(FO) sHL 
HL FO 
DE, PO+1 


BC ,PEND-PO 


A, PEND+3~—FARMO 


A 
(PEND) ,A 
IX, PARMO 
BC, 4 


HL, (NXTLN) 


HL,BC 


A, (REMS) 
Q 
NZ,RSET 


: 
: 
ec 
~ 
a 
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2955 JR RRE 
29760 RU CF ae as 
2965 JRF Z,RV 
2970 CF a 
2975 JR Z,LB 
2980 CF fgatt 
2985 JR Z,LB 
2990 CP 13 
2995 JR Z,LB 
2000 SUB 97 
S005 JF M,ERX2 
BOL SUR 26 
S015 JF PVERXS 
S020 ADD 27 
SOS L.D B,A 
S030 JR RRR 
2035 LEB LD A, (FS) 
SO4Q CF QO 
2045 JR Z,LEB1 
3050 LES L.D A, (RB) 
3055 CF Q 
BQ60 JR Z,LE4 
3065 LBS L.D A,128+64 
BO7O Fe LEX 
3075 LB4 LD A, 64 
2080 JF LEX 
2085 LB1 LD A, (RE) 
S090 CF ©) 
SIGS JR Z,LES 

; S100 LD A,128 

: 3105 JR LEX 

é S110 LBS L.D A, 64432 

We 3115 .px or Bs 

: S120 LD B,A 

S125 LD Ayo 

S130 LD (FZ) ,HL 

S135 SCHL CALL VAR#F1 

E — 3140 CF Q 

3145 JF Z,ERX2 
S150 L.D A, CHL) 

| S155 CP B 

' S160 JR Z,FARM 

31465 BIT 7,A 

f S170 JR Z, SCHL 
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S175 
3180 
3185 
S190 
S195 
S200 
S205 
S210 
S215 


eae) 


tan tant 
tet ate al ed 


aa) 
3235 
3240 
3245 


S250 


3255 
3260 
3265 
3270 
3275 
3280 
3285 
3290 
3295 
S300 
3305 
3310 
3315 
3320 


eee 
a 


Ad 
3345 
S350 
S355 
3360 
3365 
S370 
S375 
3380 
S385 


SS9O 


90 


FARM 


RHL 


CIX#0) ob 
CIX+1),H 
tx 

ix 

A, (FEND) 
A 
(FEND) ,A 
Z,ERX4 
Ao 
(Fe) A 
(RB) A 
HL., (PZ) 
A, (HL) 

z 

13 

Z 

RRR 

QO 

Qo 

Q 

oO 

ts) 

CG 

oO 

a) 

2) 

9) 

QO 

QO 

QO 

DE, 1 
ERREX 
DE,2 
ERREX 
DE,% 
ERRE X 
DE,4 
ERREX 
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The RR—RST-—RRR part of the routine reads down the next program 
line until the REM token is found at which point the variable REMS is set 
non zero, thereafter RST will branch to RSET where the next non space 
character from the parameter REM statement is tested. F$ is set if a $ 
(string indicator character) is read; RB is set if either (or) is read (array 
indicator characters), acomma, colon or ENTER token (13) forces a jump 
to LB and then the character is tested to be a lower case letter. If it is then it 
is stored, less 60 (hex) in B; any character failing the test causes an error 
escape which sets DE = 2 and calls ERREX. 

When LB is reached a parameter name has been read, and the program 
LB to LBX examines F$, RB to determine the required type and form, with 
the identifying letter, the entry to be looked for in the variables area. 

A is set to zero to initialise VAR$1 on its first call at SCHL. VAR$1 exits 
with A = Oif no more variables exist and the routine escapes with error 2, 
otherwise, HL points to the head of a variable name which is then 
compared with the subject being searched for. If not yet found the 
program returns to SCHL with A non zero otherwise PARM makes the 
head of the code which stores the head address of the variable in the 
parameter list and checks, first, that there is room for it. The markers F$, 
RB are reset and the routine returns to RRR to read the next character from 
the parameter list or exits if the end of the list was met. 


VAR$1 


The variables area consists of a sequential table of names and data whose 
head address is given by the contents of 23627/8. Chapter 24 page 166—8 of 
the Spectrum manual defines the format and coding of all of them and 
VAR$1 uses this to deliver variable addresses. 

The first three bits of each variable define its type and so enable the start 
of the next variable to be found. These bits are: 


000 not used 

001 not used 

010 string 

011 single letter name variable 
100 array of numbers 

101 multiple character name 
110 array of characters 

111 FOR loop control variable 


These codes are used to compute a relative jump at JNV to another 
relative jump which deals with finding the end of this variable and the start 
of the next. The whole process is started off by thinking of the previous, 
non-existent variable, as being of type 3 by offsetting the head of the 
variables area by 6 and jumping to J3. 
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Flowchart 9.3 


VARS 1 FIND ADDRESS OF NEXT VARIABLE. IN VARIABLES AREA 
ENTRY A= INTALISE 
A+@ CONTINUE SEARCH OF VARIABLES AREA 
EXIT Az NO MORE DATA~ VARIABLES AREA END REACHED 
A#@ A= TYPE OF VARIABLE FOUND 
HL HOLDS ADDRESS OF HEAD OF VARIABLE NAME. 
VAR$1 
STORE BC, DE 
<> INITAL\SE. 
CLEAR CARRY BIT 
SET HL TO HEAD OF VARIABLES 
SET HL BACK By 6 BYTES 
PREVIOUS VARIABLE ADDRESS)KL(VAR$) GSiF LAST ENTRY WAS TYPE 3) 


SET A = CODE TYPE OF VAR$= HL 
LAST VARIABLE. VTYPE 
HANDLED 


COMPUTE JUMP To J@ - 37 


DISPLAY ERROR * pc() 2 LONG NAME peg 
VARIABLE. 
19 BYTES 
[[ exnoe J] ERROR 


BC=19 
HL= wale ADDRESS 
ar > pet TO LENGTH 
BC = LENGTH 


ae ALS + BC 
ADD 2 FOR LENGTH BYTES 


ND OF 
LONG NAME 


BC HOLDS N° OF BYTES To NEXT VARIABLE 
HL =(VAR$)+ BC 

HL POINTS TO HEAD OF NEXT ENTRY 

A = FIRST BYTE OF NEXT NAME 


CODE TYPE 
(TIMES 2) 


NOTE : faa 'S THE ADDRESS SOF THE 
FIRST CHARACTER OF THE NAME 
ale THE Bre oe VARIABLE. 


By THE ROUTINE RESTORE BC, DE 
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The labels JO to J7 identify the sections of code which deal with the 
corresponding variable types as indicated in Flowchart 9.3. With type 5 the 
end of the name is indicated by the setting of the MS bit in the last byte, 
FVEND looks for this and the routine proceeds as if a single letter variable 
name had been read. 

Between calls of VAR$1 the variable VAR$ holds the position reached 
so far in the scan. During the routine HL points into the variables area. 

Should the routine start to generate errors, after having worked 
correctly, I would suspect that the Spectrum variable VAR$ had been 
corrupted, or the variables area had been overwritten. 


Note on the computed jump at JNV: 
The instruction JR JO is a two byte operation 


byte 0 = 24 decimal, 18 hex 
byte 1 = offset 


Since the whole table consists of such jumps the required offsets will be 0, 
2,4, 6, etc. VTYPE can only produce the eight values 0 (1) 7 shifted left one 
bit, ie 0 (2) 14 and the table covers all the possibilities. The Oth and first 
entries, both impossible, jump to the error routine. 


Listing 9.3 


2395 VARSS EQU 23627 
S400 VARFi FUSH BC 


3405 FUSH DE 

3410 CF OQ 

S415 JF NZ,NV1 
S420 OR A 

2425 LD HL, (VARSS) 
R430 LD BC ,6 

3435 SBC HL,BC 
3440 L.D (VARS) , HL 
3445 JF Js 

S450 NVI CALL. VTYFE 
3455 LD CINV+1),A 
S460 L.D DE , 666 
2445 JNV JF Jo 

3470 JR Jo 

34735 JR Jo 

3480 JR = 

2485 JR J3 

3490 JR J4 


93 


Machine Code Applications Sor the Spectrum 


2495 JR JS 
S500 JR J6é 
S505 JF J7 
3510 Jo CALL FTEX 
2515 DEFM "“VAREL 39 error" 
S520 NOF 
2525 CALL ERREX 
3530 72 INC HL 
So35 LD (VFP+2) ,HL 
S540 Ve LD BC, (VE +3) 
S545 ADD HL, BC 
S550 INC HL. 
3555 TNC HL 
2560 JV L.D (VAR) HL 
S565 LD A, CHL) 
S570 CF OBOH 
2575 JR NZ,JX 
3980 JW LD A,O 
3585 JR JXL 
2590 JX CALL VTYFPE 
S595 JX FOF DE 
2600 FOF 8c 
34605 RET 
2610 JS LD BC ,6 
2615 J=xX ADD HL, BC 
2620 JR J¥ 
3625 J4 JR J2 
S630 JS CALL. FVEND 
S635 JF ds 
3640 J6 JR J2 
3645 J7 LD BC,19 
2650 JR J=X 
3655 VAR DEFW © 
=660 VTIYPE Lp A, CHL) 
3665 AND 128+644+22 
2670 RLO A 
3675 RLO A 
2680 RLO @ 
2485 RLC A 
2690 RET 

“695 FVEND Lp HL, (VAR#) 
S700 INC HL 
S705 FYV1 BIT 74 CHL) 
Z710 JR NZ,FV2 
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3715 INC HL 

B7 BO JR FV 1 

2725 FV2 LD (VAR#) ,HL 
3730 RET 

Synopsis 


PCALL passes the addresses of BASIC variables into your code routines. 
This greatly eases the problem of data passing and most of the following 
chapter routines use this or a related subroutine OPARS. 

The first BASIC variable is assigned the name ERROR and line 2 of the 
BASIC program is reserved for error routines. 
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CHAPTER 10 
Floating Point Array Sort 


“Beyond the mountains the grass is 
greener’’’ 


German proverb 


For those of the class who have struggled this far, let me present a useful, 
practical routine, the sorting of an array of Spectrum format floating point 
numbers. This is a simple bubble sort with no practical restrictions on the 
size of the array. The time for execution depends on the square of the 
number of entries and is roughly n2/7000 seconds for n entries — some 125 
times faster than the equivalent BASIC routine. For 1000 entries the sort 
would take about 145 seconds as against five hours. 


Figure 10.1 


SORT ROUTINE — TIMING DATA 


a 
° 


n* 
t N5066 seconds 


oO NS 
os sg 


TIME (SECONDS) 
S$ 8 


> 
S 


° 3 ¢ 5 6 7-8 4 0 
ITEMS x100. N—» 
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er SORTF 
SET UP PARAMETER 
] PCALL ADDRESS TABLE. 


COLLECT PARAMETER TYPE 


Flowchart 10.1 


SET UP LENGTH 
ADDRESS 


BC LLENGTH OF ENTRY 
HLE =HEAD OF ENTRY 

COLLECT # OF DIMENSIONS 

MULTIPLY BY 2 (BY ADDITION) [LIMIT TO 127 DIMENSIONS !] 
TO SKIP AROUND DIMENSION DATA 

HFE= HEAD OF FIRST ENTRY 


(SBODY) 


D-¢ SET UP _D_AS ACTION MARKER 
1X =HFE POINT TO EXPONENT OF FIRST ENTRY 


COMPARE 2 FP NUMBERS POINTED TO 
BY IX 


(Z SET + SECOND = FIRST 
CySET : SECOND > FIRST) 


EXCHANGE. FP NUMBERS 
AND SET D #9 
(MovES 1x TO NEXT ENTRY) 


HL=1X CLEAR Cy FLAG 
BC=HLE (LAST ENTRY TEST) 


CONTINUE. 
SORT NOT 
COMPLETED 
AS n 
[+ = sige sees] SORTF 
SWOPF 
STORE BC 
B=5 

EXCHANGE (IX+) WITH (IX+5) VIAAAND C 


IXelX+1 
BrB-1 


RESTORE BC 
SET D#0O 
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The bubble sort is not the fastest but it is the simplest. Adjacent entries in 
the table are compared, and the larger, if it is not the earlier, swapped with 
the smaller: the whole table is repeatedly scanned until no inversions are 
made in a scan, at which point the table has been sorted and the routine 
exits. 

The first pass from top to bottom, will always carry the lowest value to 
the bottom. If the next pass is made from bottom to top the highest value 
will be carried to the top. With such a process the length of the unsorted 
table is continuously reduced by one entry for each pass and the time 
required can be reduced by around 50%. I will leave you to do this — I have 
done the difficult bits, parameter passing and the comparison of the 
floating point (FP) numbers. 


SORTF 


The routine separates into two sections. First the call of PCALL to set up 
the parameter list and the extraction of the located parameter followed by 
its checking. If the parameter is not of type 4 (array of numbers), the 
routine exits having done nothing: then the variables HFE — head of first 
entry — and HLE — head of last entry — are set up. As we have no 
multiplication routine the skip over the array length data in the variable 
area is done by setting the one byte of ‘number of dimensions’ into A and 
then adding it to itself; the restriction being that A does not exceed 127! A 
multi-dimension array is treated as being a single dimension array — the 
highest value is placed in x(1,1,.. .) 

The body of SORTFis straightforward. The D register is used to indicate 
that an inversion has taken place — set in SWOPF — and COMPF 
compares two adjacent numbers. COMPF exits with the Z flag set if the 
numbers are equal and the C flag is set if the second is larger than the first. 
The two FP numbers are adjacent to each other and the IX register points 
to the exponent byte with the lower address. 


Listing 10.1 

3735 SORTF CALL PCALL 

2740 LL.D HL, (FARMO) 
S745 LD (TYP T+1) HL. 
2750 TYPT LD A, (TYFT+1) 
ay aba AND 1284+644+352 
2760 CF 128 

2745 RET NZ 

R770 INC HL 
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3775 
3780 
3785 
3790 
S795 
SBO0 
2805 
3810 
3815 
S820 
S825 
SB3O 
3835 
2B40 
3845 
S850 
2855 
2860 
32865 
3870 
3875 
=B80 
388s 
3890 
3895 
S900 
S905 
2910 
S915 
S920 
2925 
2930 
S935 
S940 
3945 
2950 
2955 
2960 
29635 
2970 
39735 
2980 
2985 
2990 
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FY I 


SBODY 


NCOMF 


SAME 


TNE XT 


HFE 
HLE 
SWOFF 


SWi 


LD 
LD 


(PVL+2) HL 
BC, (PV1i+2) 
HL, BC 


(HLE) , HL. 
HL, (PFARMG) 
BC, 3 
HL. , BC 

A, CHL) 

A 

cA 

B,O 

HL, BC 

HL. 

(HEE) ,HL. 
D,o 

IX, (HFE) 
COMPF 

Z, SAME 
NC , SAME 
SWOFF 
TNEXT 
EC, 5 

IX, BC 

IX 

HL. 

A 

BC, (HLE) 
HL, BC 
NZ, NCOME: 
A,D 


A, (IX+0) 
C, (IX+5) 
(IX+0) ,C 
(IX+5) ,A 
LX 
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995 DINZ Swi 
4000 FOF BC 
4005 LOG D,l 
4010 RET 
COMPF 


Figure 10.2 details the format of an FP number. The routine is quite com- 
plicated and might be much simplified. IX points to the first (exponent) 
byte of the first number whose mantissa is at IX + 1,2,3, & 4. The second 
number has its exponent at IX + 5 and its mantissa at IX + 6,7,8 &9. The 
signs of the numbers are in IX + 1 and IX + 6. If they differ, the positive 
is greater than the negative. If they are of the same sign, their exponents 
are compared. In the Spectrum representation the exponents are all offset 
by 128 and the exponents may be compared and the carry flag tested. The 
significance depends however on the sign of the mantissa. With positive 
mantissas the larger exponent belongs to the larger FP number; with 
negative mantissas the larger exponent belongs to the smaller FP number. 
The B register is set non zero for negative mantissas. 

Numbers with the same sign and equal exponents must be compared byte 
by byte until a discrepancy, if any, is detected. The signed bytes, when 
compared, must be tested by JP P,... or JP M,... operations as a carry 
from a borrow will only be set with a negative number. The remaining 
mantissa bytes can be tested on the carry flag as they are all unsigned. The 
significance of the decision at BTL or BTG is decided on the sign, as 
recorded in the B register, of the mantissa; failing to make this correction 
will result in the positive numbers being separated from the negative ones 
and both sets sorted in order of descending absolute (unsigned) size. 


Listing 10.2 


4015 COMFPF LD B,Q 


4AO2o BIT 7, ¢IX+1) 
4025 JF Z,CL1 

4020 CLA BIT 7, (IX+6) 
4035 JR Z,VILV2 
4040 CLS LD A, (IX+0) 
4045 CF (TX+5) 

4050 JF M,ViGVS 
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4055 JF Z,CL4 
4060 JR VILV2 
4065 CL4 LL.D B,255 
4070 JF XEQ 
40735 Cul BIT 7, (IX+6) 
4O8oO JR NZ,V1iGV2 
40835 CLS LD A, (IX+5) 
4090 CF CIX+0) 
4095 JR C,ViGv2 
4100 CLé JR NZ,VILVS 
4105 XEQ LD A, (IX+1) 
4110 CF (IX+6) 
4115 JR Z,XEQM 
4120 JF F,BTG 
4125 JR BTL. 
4130 XEQM LD A, (IX+2) 
4135 CF (Ik+7) 
4140 JF C,BTL 
4145 JF NZ,BTG 
4150 L.D A, (1X+3) 
4155 CF CIX+8) 
4160 JF C,BTL 
4165 JR NZ,BTG 
4170 L.D A, CIX+4) 
4175 i (IX+9) 
4180 JR C,BTL 
41985 JF NZ,ETG 
4190 RET 
4195 ViGV2 Lp As 
4200 CF 1 
4208 RET 
4210 ViILVS LD ys 
4215 CF mis 
422g RET 
4225 BTL. BIT 1,8 
4230 JF NZ,ViGV2 
4235 JR VILVS 
4240 EBTG BIT 1,8 
4245 JF NZ,VILV2 
250 JR ViGV2 
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Flowchart 10.2 4 
B=O CLEAR -V@ MANTISSAS FLAG 
TEST SIGN BIT OF FIRST MANTISSA 


N1-Vé no YES _bit 7=0 


TEST SIGN BIT OF SECOND MANTISSA 
Ni-ve 


N2+ve YES 
BOTH MANTISSAS - VE 


COMPARE EXPONENT BYTES 
FLAGS= 1X9) - (X45) 
y aE 92 


Ni+Vé 


EXPONENTS EQUAL TEST SIGN BIT OF SECOND 


MANTISSAS BOTH -V@ 
USE B pee AS A FLAG 


LARGER EXPONENT 
MORE - ve 


COMPARE EXPONENT BYTES 
Y2-¥2 FLAGSS (1X+5) - (1X0) 
2. % 


YES 


LARGER EXPONENT 
LARGER VALUE 


LOWER EXPONENT 
LOWER VALUE 


EXPONENTS EQUAL 
MANTISSAS BOTH +V@ 


FLAGS = (1X+2)-(1X+7 
(SECOND M, 932 wy) 
le) 


NO 


(rate anriosa By ibs) 


LAGS = (IX+4 
FOURTH MAWNTIS: 


CLEAR Z FLAG CLEAR Z FLAG 
SET CARRY FLAG ‘CLEAR CARRY FLAG 


— SZ 


103 


Machine Code Applications for the Spectrum 


Figure 10.2 
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SORTF — a practical example 


To print a list of competitors in order of descending points. (There are not 
more than 999 competitors and their points/times may be represented by a 
number less than six digits. 

The data is in an array a( ), the points of competitor n are in a(n). If we 
sort a( ) we will indeed put the entries in numerical value order but we will 
lose the competitor identification. 

If we code in BASIC: 


FORn = 1TO... 
LET a(n) = 1000* a(n) +n 
NEXT n 


then each entry will contain both pieces of information; as decimal digits 
the last three will identify the competitor and the others the points of that 
competitor. Note that because of the way the Spectrum handles floating 
point numbers the apparent value of a (n) should not be greater than about 
1 000 000 000. We can now write: 


LET 1 = USR SORTF 
REM a( ): 


and the array will be sorted with the higher marks first and the competitor 
number trailing along behind as the last three digits. The nth entry can then 
be printed by: 


PRINT INT (a(n)/1000); INT(a(n) — 1000* INT(a(n)/1000)) 


There is just one other consideration. Some entries in a(_) may be stored 
in the integer form internally, which will upset SORTF. Before using it, 
each element must be in floating point form, and the best way to do this is 
to use something like 


LET a(i) = a(i) + 65537 — 65537 
For an M entry list the program looks like: 


FORn = 1TOm 

LET a(n) = 1000* a(n) + n + 100000 

NEXT n 

LET 1 = USR SORTF 

REM a( ): 

FORn=1TOm 

LET a(n) = a(n) — 100000 

PRINT INT(a(n)/1000); INT(a(n) — 1000*INT(a(n)/1000)) 
NEXT n 
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which will print the points followed by the competitor number. Where two 
competitors have the same number of points the output will be in 


descending competitor number order. 
All you need to do is get the data into a( ) to start with and the routine 


will do the rest in the twinkling of an eye. 
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Passing other Parameters 


So far we have only a few routines which we call from the BASIC. It is quite 
easy to assemble each separately (with its own load address and its own 
copies of common subroutines), load them and remember to call them 
correctly as required. The drawbacks become evident when they have 
many subroutines in common and these are needlessly multiplied. 

The solution I have adopted is shown in Listing 11.1. All the routines 
etc., are assembled together (or as many as are needed) and they are called 
through identical code sequences, which are thus all of the same length. 
First the SP save for the error escape back to line 2 (Chapter 9); then the 
storing of all the used registers, the specific subroutine call — DRAWL, 
MAP$etc., and finally the jump to the common return label TRAP$ where 
the registers are restored and the RET to BASIC is made. 


Listing 11.1 

OOOS ORG 640000 

OOLO LD (ERROR) , SF 
OO1LS FUSH AF 

OO20 FUSH BC 

NO25 FUSH DE 

OOO FUSH HL 

OO35 FUSH Ix 

0040 CALL DRAWL 

O04s JF TRAPS 

oOos50 LD (ERROR) , SF 
oosg5 PUSH AF 

0060 FUSH BC 

0065 FUSH DE 

OO7O FUSH HL 

0075 PUSH IX 

Oo080 CALL SATTR 

008s JF TRAPS 

0090 LD (ERROR) , SF. 


0095 PUSH AF 
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O100 
O105 
O110 
O115 
O120 
O125 
O10 
OL35 
O140 
O145 
O150 
QO1S5 
0160 
0165 
0170 
O175 
0180 
O18s 
0190 
O195 
O200 
0205 
O210 
O215 
O220 
O225 
OBO 
O235 
o240 
0245 
oO250 
o255 
0260 
0265 
O270 
O275 
O2B80 
O285 
OBSO 
O295 
OS00 
O205 
O310 
O215 
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PUSH 


TRAFS 


TRAF'E 


TRAPS 


1. oP 


, SF 


SF 


, SF 
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These common entries are all 16 bytes long and the routines can be called 
as an offset to the load address: 


DRAWL at USR+0 
SATTR at USR+16 
BLOCK at USR + 32 


and so on. (The head of) a BASIC program could then look like Listing 
11.2. This has the advantage that, if the load address has to be changed, 
only line 10 needs attention and, after the initial setting up, the routines 
can be called by mnemonics instead of numerial values. (The routines 
SATTR and DRAWL are described in Chapters 13 and 14). 


Listing 11.2 


1 LET error=90: GO TO 16 
2 FRINT "ERROR ="serror:s STOF 
16 LET base=460000 
11 LET drawl=baseto 
12 LET sattr=baset16 
12 LET block=base+t32 
14 LET sortf=baset49 
15 LET gcell=baset+64 
16 LET map=baset8o 
17 LET ivert=baset+96 
18 LET movec=baset112 
19 LET svert=baset126 
29 LET drawa=baset144 
21 LET demol=baset140 
22 LET demo2=baset+174 
<4 60 SUB 70: FAUSE 200: GO SUB BO: GO SUE 
200: GO SUB 300: GO SUB 400: GO SUB 
9000; GO TO 21 
30 LET b=250 
41 DIM k#¥(b,2) 
42 FOR x=1 TO b 
45 LET k#(x,1)= CHR 255 
44 LET k¥(x,2)= CHRE 255 
45 NEXT x 
SO LET k=O 
Sl LET ol=0 
93 LET l= USR movec 
24 REM read cursor postian 
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56 FRINT AT G,O," "s FRINT AT 

O,O;1: PORE 23540,255 

27 IF l=ol THEN LET 1=65535 

98 LET k=k+1 

99 LET k#(k,2)= CHR INT (1/256) 

60 LET k#(k,1)= CHRE INT (1-254*¢ INT 
(1/256))) 

61 IF ki THEN GO TO 58 

= LET m= USR drawa 

63 REM k#O): 

64 LET ol=1] 

65 FRINT AT O,ésk 

664 GO TO 53 

70 LET l= USR sattr 

Oa REM 20505 Lost bo O 

72 LET l= USR sattr 

75 REM 216.12 551523 16. 

74 LET l= USR sattr 

7S REM :24,0,31,4,24, 

76 RETURN 

80 LET l= USR map 

81 RETURN 
100 LOAD "" CODE : LOAD "" CODE : GO TO 1 
290 DIM a(44) 
©O1 FOR m=1 TO 44 
202 LET a(m)= RND #107 C INT (¢CZO# FIND 9-159) 
203 NEXT m 
294 GO SUB 220 
295 LET l= USR sortf 
296 REM ad): 
©O7 FAUSE 1 
£08 GO SUB 220 
299 RETURN 
220 CLS 
22l FOR m=1 TO 44 STEF 2 
eee FRINT atm) ,acmt+1} 
cao NEXT m 
224 RETURN 
“00 PRINT AT 3,5: 
S01 FOR k=O TO 255 
202 LET l=deamol 
2035 REM k:90,0,14,7, 
204 NEXT k 
210 RETURN 


"TILE COLOUR DEMO." 
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400 DIM (5 
401 FOR g=1 TO 500 

402 LET g(S)= INT (255 RND ) 
403 LET gC3)= INT C31i# RND ) 
404 LET g(4)= INT (23% RND ) 
405 LET g(i)= INT (g(3)* RND } 
406 LET g(3)= INT (g(4)* RND ) 
407 LET l= USR demo? 

408 NEXT g 

409 RETURN 

9000 FOKE 23675,0: FORE 23676,150 
9001 FOR x=0 TO 224 STEF 2 
9002 LET l= USR gcell 

9003 POKE 38400, x 

9004 NEXT x: RETURN 


I now have some explaining to do — the REM statements in Listing 11.2. 
Back in Chapter 9 I showed how variable NAMES could be passed into 
machine code, but skipped over as too complicated for then, the passing of 
numeric values and strings. In Chapter 10 we used a passed array name to 
provide the required pointer(s) for SORTF. Now we will deal with the 
omissions of Chapter 10. 


OPARS (Other Parameters) 


These must be compatible with the name parameters collected by PCALL, 
that is, be present in the same REM line along with the name parameters. 
The easiest way is to rely on splitting the parameter list into two parts: first 
the names terminated by a colon and then, after the colon the values and 
strings. We allow the possibility that there are no name parameters but still 
insist on the colon as marking the start of the value / string part. 

The specification for these parameters is: 


Each entry, including the last, is terminated by a comma. 
The REM statement is terminated by an ENTER token. 


Values are unsigned, 16 bit integers. (Their values are to be found in the 
variables VPARO, VPARO +2 etc.) 


Strings are deliminated by double quotation marks (‘‘), may be of any 
length and must be terminated by a comma after the closing quotes. A 
string must not contain double quotes. The address of the first character in 
each string is to be found in the variables SPARO, SPARO + 2, etc. 
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No data is passed concerning the relative positions of the values and 
strings in the parameter list; only their relative positions within each class 
are preserved. 


To enable 0 to be passed as a value a subsidiary byte, SBITZ is used and 
has bits 7,6,... set according to whether VPARO, VPAR+2 etc. are 
valid. 


OPARS will force error exits: 


10 failed to find end of REM statement 
11 non digit in number 

12 too many parameters (more than 6) 
13 false read of number 

14 number greater than 65535 


Listing 11.3 

4255 OPARS LD HL. , SFARO 
4260 LD (SFZ) , HL 
4265 LD HL, VF ARO 
4270 L.D (VEZ) HL 
4275 L.D HL. © 
4280 L.D (SFARO) , HL 
4285 LD HL, SFARO 
42oo LD DE, SFARO+1 
4295 LD BRC ,SBRITZ-SFARO+1 
300 LDIR 

305 LD HL, (NX TLD 
41a INC HL 

4315 INC HL 
4320 L.D (VF L+2) ,HL 
4325 VEL LD BC, (VFPL+2) 
230 INC HL 

Sibel INC HL 
4340 GNEBi CALL GETEY 

4345 CF 13 
4350 RET Zz 

ben be) CF a 

AZo JR NZ,GNEL 
4365 GNES CALL GETBY 

4370 CF 13 

4375 RET Zz 

4280 CF Morey 
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S85) Jr Z,GNE2 
43S90Q Cr non 
4395 JR Z, EOF AR 
4400 CE woes 
4405 JF 2Z,STSTR 
4410 Cr ne 
4415 JF M,ERXil 
4420 CF Wau 
4425 JF P,FERX1i1 
4435 SUB woe 
4440 FUSH HL. 

4445 PUSH BC 

4450 or A 

4455 LD HL, (NUMB) 
4460 ADD HL,HL 
4465 JR C,ERX14 
4470 ADD HL, HL. 
4475 JR C,ERX14 
4480 LD BC, (NUME) 
4495 ADD HL,BC 
4490 his C,ERX14 
4495 ADD HL, HL. 
4500 JR  C,ERXi4 
4505 LD B , QO 

4510 LD CYA 

4515 ADD HL,BC 
4520 JR C,ERX14 
4525) LD (NUMB) , HL 
4530 LD. yd 

4525 LD (NNR) 5A 
AS4o0 FOF BC 

4545 FOF HL 

ASSO JR  GNE2 
4555 ERX14 pb DE,14 
4S CALL ERREX 
4565 EQFAR FUSH HL 

4570 FUSH BC 

4AS75 LD A, (NNR) 
4580 cr oO 

4585 Je Z,ERX1i3 
4590 LD A, (SEITZ) 
4595 SRL A 

4600 SET 7,A 
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4605 LD (SBITZ) ,A 
4610 LD Hi., (NUMB) 
4615 LD BC, (VFZ) 
4620 LD (VPLZ+1),BC 
4625 VFL LD (YVPL24+1) ,HL 
4630 INC EC 

46355 INC BC 

4640 LD (VF Z) BO 
4645 LD HL. , NUMB+2 
4650 OR A 

4655 SBC HL,BC 
4660 JF Z,ERXi2 
4665 LD HL, © 

AG7O LD CNUME) , HL 
4&7 LD A,o 

4680 LD (NNEOD , A 
4685) FOF BC 

4690 FOF HL 

4495 JF GNE2 

4700 STSTR FUSH HL 

ATOS FUSH BC 

A710 EX DE, HL 
4715 LD BC, (SFZ) 
4720 LD HL, VF ARO 
4725 OF ay 

AT3Q SBC HL,EBC 

AT 35 JR Z,ERX12 
4740 EX DE, HL. 
474s LD (VFLS+1),BC 
4750 VPLS L.D (VEPLS+1) ,HL 
4755 INC BC 

4760 INC BC 

4765 LD (SFZ),BC 
4770 FOF BC 

4775 FOP HL 

4780 RFORC CALL GETBY 
A785 CF vate uate 

A79Q Jr NZ, REORC 
4795 GNBS CALL GETBY 
4800 cre tea: 

4805 JF Z,GNE2 
4810 CF 2 

4815) RET Zz 

4820 JF GNBS | 
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4925 GETBY DEC BC 


Ago BIT 7, 
4835 JR NZ,ERX1O 
4840 LD A, CHL) 
4845 INC HL 

4gso RET 


49355 ERX10 LD DE,10 
4860 ERXAA CALL ERREX 
4865 ERX11 LD DE,11 


4870 JR ER XAA 
46875 ERK12 LD DE,12 
4880 JR ERXAA 
4985 ERX13 Lp DE,13 
4890 JR ERXAA 
4893 VEZ DEFW © 
4900 SPZ DEFW © 
4905 SFARG DEFW a 
4A91o DEFW © 
4AGiSs DEFW © 
4920 DEFW © 
4925 DEFW © 
4AGad DEFW © 
49235 VFARG DEFW o 
4940 DEFW © 
4AGaS DEFW © 
4GSo DEFW © 
4935 DEFW © 
4960 DEFW © 
4°65 NUME DEFW © 
4970 NNF DEFER © 
4975 SBITZ DEFB o 
4980 DEFW © 
Operation 


As the routine may well be called many times all the workspace is first 
cleared and the result pointers, SPZ for strings and VPZ for values, are set 
to point to the heads of their respective lists, SPARO and VPARO. 

At VPL BC is loaded with the number of characters in the parameter line 
following the call of USR... and HL is set up to point to the first byte. 
GETBY reads bytes in sequence using HL and decrementing BC (error 10if 
BC goes negative) which are preserved for this use; the read character is in 
the A register. 
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Flowchart 11.1 


OPARS 


CLEAR OUTPUT TABLE. AREA 
INITIALISE POINTERS SPZ + VPZ 
SET HL TO HEAD OF PARAMETER DA 
(CTO LENGTH OF REM LINE. (BYTES) 


READ To < 
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END OF STRING — 


‘T END OF NUM 
omit sPAad Cas) ; 
Gn) NO Cane Sts 
Cope 
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MOVE HUTO Mist CHARACTER 
OF SUBYECT STRING tC Aca» No 
NOT A 
mn sip OST 
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l ERROR 11 | 
A= BIN VALUE FOR DIGIT 


FORM LOAD INSTRUCTION 


STORE Ht+ E Be 
CLEAR 


HL=NUOMBER Bene t READ 
STORE STRING ADDRESS 

MULTIPLY HL BY 10 AND ADD IN VALUE 
OF BYTE JUST REA 

CHECK Cy BIT AT AL STAGES 

STORE PARTIAL RESULT IN NUMB 

SET NNR#@ RESTORE HL + BC 


| 
FORM NEXT STRING STORE ADDRESS 
STORE IN PZ. OVERFLOW EXIT 


RESTORE HL+ BC ] ERROR 14 


& oy 


STORE. BC+ HL 


READ To END 
OF STRING 


SET FLAG BIT IN 38IT2 
COMPUTE LOAD INSTRUCTION 


LOAD NUMB INTO VPAR TABLE 
SET UP NEW VPZ. FOR NEXT 


ERROR |3 


CONTINUE AFTER 


RESTORE HL+ BC 
END OF STRING 


| ERROR 12 


CONTINUE. 
AFTER END 
OF NUMBER 


LOAD A WITH 
BYTE 


INCREMENT H 
(BYTE. POINTER) 
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At GNBI characters are ready until either a 13 (ENTER token) or a: is 
met; the colon marks the end of the name parameter part which may be 
empty. 

At GNB2, the characters after the colon are analysed; a 13 terminates the 
routine; spaces are ignored; a comma is recognised as an End Of 
PARameter (jump to EOPAR) and a double quote is recognised as the 
start of a string parameter to be dealt with at STart STRing (jump to 
STSTR). Anything left must be a (decimal) digit or an error. 


Numbers 


The ASCII codes for digits run sequentially from 48,, for 0 to 58,, for 9 
and the colon has ASCII code 59,,. Subtracting the code for 0 leaves a 
valid binary representation of the digit just obtained. 

The HL and BC registers are saved for their next use by GETBY and HL 
loaded with NUMB which holds the partial result of this value evaluation 
(or zero). HL is multiplied by 10 through shifting and addition and then A 
is added in to give the new partial result which is restored in NUMB. At 
each stage HL is tested for overflow and error 10 is generated if need be. 
NNR is set non-zero as an indicator that a number is being read and HL, 
BC are restored ready to read the next input byte. 


End Of PARameter (EOPAR) 


If NNR is not set, an error condition (double commas or missing value) 
raises error 13, otherwise a valid number has been read and a new bit is set 
in SBITZ. If the number were zero the VPAR entry would be zero. So a 
non-zero entry cannot be used as a test for the presence of an entry as it can 
be in SPAR for strings since 0 is head of memory in ROM. VPL2 is a 
computed load address for HL into the VPAR list and then VPZ is 
incremented by 2 to point to the next two byte entry. If it points to 
NUMB + 2 the table has overflowed and error 12 is generated. NUMB and 
NNR are cleared in readiness for the next value parameter. 

N.B. The sequence of the labels VPZ to SBITZ should not be altered 
although the number of elements in the VPAR and SPAR lists may be 
changed. 


String start (STSTR) 

HL points to a byte just after the double quote which has been read by 
GETBY. HL and BC are stored, and HL — the address of the first 
character in the string — is stored in DE; OR A clears any carry flag and 
SPZ is tested against VPARO which marks the end of the SPAR list. Error 
12 is again generated if there are too many string parameters. VPL3 is a 
computed load of the restored HL (from DE) into the string address table. 
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After the string address table has been loaded RFORC reads down the 
string for the terminating double quote and then to the concluding comma 
or terminating 13 token. 


Synopsis 


OPARS allows constants, integer values and strings to be passed into your 
machine code from the BASIC program. These parameters must follow a 
colon in the REM statement. 
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CHAPTER 12 
BASIC Block Delete 


If you wish to remove a section of lines from your BASIC program, 
because it has become obsolete for example, Then you normally have to 
type in each line number in turn, which can be very time consuming. Many 
other micros have a DELETE a,b or similar command which removes all 
lines from a to b. The following routine uses OPARS to delete any 
number of lines. It is best to refer to page 166 of the Spectrum manual 
while following this routine. It requires two value parameters, both line 
numbers, and deletes from the first up to, but not including, the second. 
The technique is one of individual line deletion followed by the adjust- 
ment of VARS. The BASIC system should be set up by CLEAR com- 
mands both before and, especially, after running the routine. 

First some subroutines to collect individual lines for examination (see 
Flowchart 12.1). Note that they are essentially different ways of entering a 
common block of code. 


SUPLN 


Sets UP LiNe pointers, used by the other routines, to point to the first line 
of the BASIC program; it and the others all destroy their input registers 
and exit as follows: 


HL contains the (new) line number 

BC the length, in bytes, of the line of data 
DE points to the first character of the line 
Z flag set if there is no more data 


The variables M1, M2, M3, M4, and MS are used as follows: 


Ml address of first byte of line number 

M2 length of this line in bytes (= BC) 

M3 line number of this line (= HL) 

M4—M5 _ temporary storage while a line is being deleted 
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Flowchart 12.1 


(CONTINUE) CNXLN SUPLN (SET uP) 
HL = OLD HEAD ADDRESS 
BC=0 GTH 
HL== HL+BC+4 HL= HEAD OF BASIC 


HL 
RESTORE TO Bee = HEAD OF VARIABLES 
LINE IN HL CLEAR Cy (END OF green 


M1=HL 
HL=M 
HL=HL+2 POINTTO LENGTH BYTES 
: COMPUTE LOAD BC 
BC =LENGTH OF LINE 
M2=BC 
MbsHL+2 
ere = FIRST BYTE OF LINE (ADDRESS) 


"COMPUTE LOAD HL(WITH LINE. NO.) 


- 


HL= ae NO. NO. Ore IRUM STYLE) 
SWOP H 


M3e Line NO. (LS BYTE FIRST) 


HL = LINE # SAND M3) 

BC = LENGTH OF LINE 

DE= ADDRESS OF FIRST BYTE 
Mi= LINE # ADDRESS 


(COLLECT LINE DATA FROM BASIC PROGRAM) 
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Listing 12.1 


4985 SUFLN 
4990 SUFLM 
4995 

SOO00 

5005 

S010 

S015 

HOLO SUPLL. 
SOLS 

5OR0 

9035 SFLA 
2040 

S045 

BOSO 

SOSS 

SOGO 

5065 

9070 SFLE 
SO75 

SO80 

S085 

DO9IO 

5095 

3100 CNXLN 
S105 

S110 

o115 

S120 

S125 

S130 

5135 

2140 RESLN 
3145 

S150 Mi 
2155 M2 
u160 MS 
3165 M4 
s1l7O MS 
5175 FROGS 


Chapter 12 BASIC Block Delete 


HL, (PROG#) 
(M1) HL 

BC, (VARSS) 
A 

HL. , BC 

Z 

HL, (M1) 

HL. 

HL. 
(SPLA+2) ,HL 
BC, (SFLA+2) 


(SPLB+1) ,HL 
HL, (SFLE+1) 


BC, (M2) 
HL, (M1) 
HL, BC 
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Flowchart 12.2 


122 


BLOCK 


VPARG START LINE NO 
VPAR@+2 END LINE NO 


SET _UP LINE EXTRACTION 
ROUTINES 


BG? START LINE NO 
LINE # TOO LOW HLT HL-BC 


HL=HL+BC RESTORE FROM 
BC= END LINE NO 

CLEAR Cy FLAG 

HL, HL BO 


NO 


THIS LINE TO BE 


LINE NO. Too DELETED 


HIGH OR= END 


HL= HEAD ADDRESS 
petals LINE 


M5= Mi (HEAD OF 

NEXT LINE) 
HL>VARSS END OF BASIC + 1 
BC=M5 


HL = HL-BC LENGTH TO BE MOVED 
BC= HL 
HL=M5 


DE = M4 

LDIR MOVES DATA FROM HL) DE 
HL = = LENGTH LOST (IN BYTES, 
BC = VARSS 
RESET END OF PROGRAM POINTER 
HL = M4 (HEAD OF DATA JUST MOVED UP) 


Chapter 12 BASIC Block Delete 


CNXLN (Continue with NeXt LiNe) 


This sets up the registers in a similar way to SUPLN, but for the next line in 
the program. It sets HL not to PROG, as SUPLN does, but to 
M1+M2+4, which is the first byte of the next line. 


RESLN (REStore LiNe) 


After a line has been deleted the old line location(s) now contains the head 
of the next, non deleted line. RESLN resets the registers and storage 
locations for his new line. 


Operation of SUPLN 


On entry HL contains the location of a line, initially the first one. This 
address is stored in M1 and compared with the value of VARS. The RET Z 
will return if the HL has reached VARS ie there are no more lines. 

At SUPLL, HL is incremented by two to point to the line length bytes 
and this value is stored in SPLA + 2, which is the second half of the next 
instruction. The computed instruction at SPLA loads BC with the length 
of the current line, and it is stored in M2. The computed instruction at 
SPLB then loads HL with the line number, which is reversed, so registers H 
and L are swopped, stored in M3 and a return made. In all normal 
circumstances the Z flag will be unset because no instruction apart from the 
SBC test after SUPLM will affect any flag. Take care that at the entry 
RESLN the Z flag is NOT set. 


Operation of BLOCK (see Flowchart 12.2) 
BLOCK expects two parameters and its call will look like: 


LETL=USR... 
REM : 174, 8234, 


Should the second parameter be less than the first no action will take place. 
OPARS is called to read the two parameters which will be located in 
VPARO and VPARO + 2 as two 16 bit numbers. 

SBITZ is checked to ensure that only two parameters are present (error 
20 otherwise) and the value of the second parameter is checked to be a valid 
line number (less than 10000). SUPLN is now called to point to the first 
BASIC line and at TSTLN the line number is checked against the value of 
the first parameter; if the value is too small CNXLN is called to collect the 
next line and the process repeated whilst lines remain to be checked; if the 
line number is equal or greater than the first parameter a jump is made to 
BDLE1. 
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Listing 12.2 


3180 
S185 
S190 
S195 
S2OO 
S205 
we2lo 
s215 
220 
S225 
5230 
bar 
5240 
245 
aeud 
5255 
5260 
ae26s 
g270 
5275 
5280 
5285 
5290 
5295 
ha O18) 
S305 
2310 
S215 
S320 


“Toe 
toatl be teal 


S30 


S335 


5340 
o345 
S350 
Ker Be be] 
5240 
3365 
S270 
aa75 
S380 
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BLOCK 


BLAR 


BLA 


TSTLN 


BDLEL 


BDLES 


OF ARS 

A, (SBITZ) 
128+64 
Z,BLA 
DE , 20 
ERREX 

HL, (VFARO+2) 
BC, 10000 
A 

HL, BC 

FP, BLRE 
SUPLN 

BC, (VFARO) 
A 

HL, BC 

FY BDLEL 
CNXLN 
Z,BDONE 
TSTLN 
HL. , BC 

BC, (VPARQ+2) 
A 

HL. , BC 
F,BDONE 
HL, (M1) 
(M4) ,HL 
CNXLN 
Z,BDONE 
HL, (M1) 
(MS) , HL 
HL, (VARSS) 
BC, (MS) 

A 

HL, BC 

HL 

BC 

HL, (MS) 
DE, (M4) 


A 
HL, (MS) 
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5285 LD BC, (M4) 
5390 SBC HL,BC 

5395 FUSH HL. 

5400 FOF BC 

5405 LD HL, (VARSS) 
S410 SBC HL,BC 

S415 LD  (VARSS) ,HL 
5420 LD HL, (M4) 
5425 CALL RESLN 

54350 JR NZ,TSTLN 


54235 BDONE RET 


BDLE1 


The line number is now checked against the second parameter, the upper 
line limit. If this is less than the limit the line is to be deleted at BDLE2, 
otherwise the routine exits at BDONE to the cruel, cold world of a 
diminished BASIC program. 


BDLE2 


This line is to be deleted. The head address is stored in M4 and CNXLN is 
called to determine the head address and presence of the next line. BLOCK 
specifically will not delete the last line of the BASIC program. 

BC is loaded with the number of bytes to be retained (from the head of 
the line called up by CNXLN up to the address in VARS) and DE/HL are 
set so that the LDIR instruction will move everything up, so covering the 
unwanted line. VARS is then reduced by the total length of the removed 
line and RESLN called (with the Z flag not set). 

The process is now repeated at TSTLN where the next line is tested and, 
if need be, deleted. 
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CHAPTER 13 
Setting the Attributes Area 


The attributes area controls the INK and PAPER colours and the 
BRIGHT and FLASHing status of each character square. They are ar- 
ranged sequentially from location 22528, in the form of 24 rows of 32 col- 
umns. This routine allows you to set all or any of the attributes for a rec- 
tangular area by specifying the top left and bottom right hand tiles of the 
area involved, together with the required attribute(s) byte. 

The call is 


LET L = USR... 
REM :X,, Y,, X,, Y,. A, 


The Xs must be in the range 0-31 and the Ys in the range 0—23. The A 
value is the decimal number, collected from Figure 13.1 which defines what 
is to happen at a tile position. Remember, you can disguise a messy screen 
redrawing by setting paper and ink colours the same to start with and then 
revealing all by setting them differently when done. 

Two errors may be generated by the routine: 


30 ‘top left’ corner below or to the right of ‘bottom right’ corner 
31 either specified tile is outside the attributes area 


Operation (see Flowchart 13.1) 


OPARS collects the value parameters which are assumed to be present, and 
STRTA is calculated to be the address of the first attributes byte to be 
loaded. 

CDIFF holds the difference + 1 in the tile columns (X values) specified 
and RDIFF the row difference + 1. If either the row or column values are 
the same a single row or column will be handled. When several calls are 
made remember that where a bottom right corner of one call is the same as 
the top left corner of another there will be a one tile overlap with the later 
overwriting the earlier. 

Once RDIFF and CDIFF have been set up the double loop in the routine 
ATTRL F 13 write RDIFF rows of CDIFF attributes; each row of 
attributes commences 32 bytes beyond the start of the previous row and 
there are none of the complications of pixel plotting to be dealt with. 
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Figure 13.1 


SAONVIISINZIS Lid - VAY SALASIY LLY 


NI SLUM ANV 
YAdvd NJ? ONIHSV 14 ANID CINOM L91=/+ZE + BTZI OS 


SLHM Z 9S 
mMoTIaA 9 «| Bb 
NVWAD Ob 
Na) + | & 
VINSIVW ¢ 74 
qau¥ Z | 9! 
anne 1 g 
wvig O | O 
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Flowchart 13.1 


SATTR 


MY 


COMPUTE ADDRESS OF FIRST ATTRIBUTES BYTE 


H ERROR 3! i 


A=LIN,— LIN, 


RDIFF= A 
ATTRB = VPAR®G+8 


| ATTRL | 


ERROR 3o 
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Machine Code Applications for the Spectrum 


Flowchart 13.2 


ATTRL 


yy RDIFF NUMBER OF ROWS 


HL=FIRST ATTRIBUTES BYTE ADDRESS 


STACK BC 

STACK HL 
B=CDIFF NUMBER OF BYTES /ROW 
A=ATTRB ATTRIBUTES 


WRITE TO ATTRIBUTES AREA 
DECREMENT ROW BYTE COUNT 


RESTORE HL 
HL=HL+32 MOVE To 
RESTORE BC NEXTROW 


B-B-1 DECREMENT 
ROW COUNT 


Listing 13.1 


so10 
Sag15 
ba bor 
S525 
S530 
SoS5 
5540 
2545 
S550 
Kal ba as ba 
3560 
5565 
So70 
S575 
5580 
S585 
S59Q 
SSeS 
SGOO 
S605 
2610 
9615 
S620 
S625 
S630 
S635 
5640 
5645 
S650 
S65 
5660 
5665 
5670 
9675 
5680 
3685 
6PO 
54695 
5700 
5705 


3710 


SATTR 


ATTRE 
CDIFF 
RDIFF 


CALL 


DEFR 
DEFEB 
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OF ARS 
HL, (VEARO+2) 
HL, HL 

HL. HL. 

HL, HL. 

HL. , HL. 

HL, HL. 

BC, (VFARO) 
HL. , BC 

BC, 1629446144 
HL., BC 

(STRTA) ,HL 

A, (VFARO) 


me 
seat ae 


FY ERX 24 
EA 
A, (VPARO+4) 


FY ERX S41 

B 

C,ERXS0 

A 

(CDIFF) ,A 
A, (VFARO+2) 
24 

FY ERXS1 
BA 

A, (VFARO+6) 
24 

FY ERXS1 

E 

C,ERX30 

A 

(RDIFF) A 
A, (VPFARO+8) 
(ATTRE) A 
ATTRL 


O 
ra) 


oO 


131 


Machine Code Applications for the Spectrum 


S715 STRTA DEFW © 
o720 ERX20 LD DE, 30 


a725 CALL ERREX 
S730 ERX31 LD DE, 31 
7235 CALL. ERREX 


Listing 13.2 


) 5740 ATTRL LD A, (RDIFF) 

5745 LD  B,A 

| 5750 LD HL, (STRTA) 
5755 ATTRN FUSH BC 
5740 FUSH HL. 
5765 LD A, (CDIFF) 
5770 LD #B,A 

5775 LD A, (ATTRE) 

5780 ATTRM LD (HL) 4A 

| 57385 INC HL 

| 5790 DINZ ATTRM 

| 5795 FOF HL 

1) 5800 LD BC,32 

if 5905 ADD HL,BC 

i 5810 FOF BC 

i 5815 DINZ ATTRN 
520 RET 
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CHAPTER 14 
Hi Res Graphics 


The Spectrum has a display resolution of 256 pixels horizontally by 192 
vertically. In this chapter there are routines to draw lines and move acursor 
across it, and an elementary drawing program is also presented. 

The only way to draw a line between two points on the Spectrum display 
is to plot, point by point, all possible points on the line from X,, Y,toX,, Y, 
and preferably to do it quickly. 

One way to do it which gives reasonable results is as follows: find 
increments DX and DY, not necessarily integer or positive, in X and Y 
which can be repeatedly added to X,, Y, and which will cause X,, Y, to 
move towards and reach X,, Y,. This is, in principle, what happens when 
you draw a line with a straight edge on graph paper. 

Problems now arise. How are we to deal with the fractions when we have 
only dealt so far with integers? Fear not! The answer lies not with floating 
point numbers but with scaling. 

Scaling is a very common technique in machine code programming for 
dealing with values outside the normal byte or word range of the machine. 
By way of example we will take the points in X and Y on the display screen 
to be given by 16 bit numbers; the MS byte will represent actual plottable 
points and the LS byte the fractional, non plottable, parts. 

We take the arithmetic (ie signed) differences between the Xs and 
between the Ys and divide each by 256 (by changing the byte significance) 
to generate the differences DX and DY. This will always work as the largest 
difference between two Xs can only be 255, but we must remember to treat 
DX and DY as 16 bit values and propagate their sign bits through the MS 
byte. To reduce the plotting work to be done DX and DY are both shifted 
left until their most significant digit amounts to one quarter of a plotted 
point; more than this results in a ragged line, less takes longer, the choice is 
yours and you ought to experiment by modifying the routine SDIFF which 
sets up DX and DY before they are used. 


Listing 14.1 


S825 FLINE CALL OFARS 
S830 LD A, (VF ARG) 
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S835 LD B,A 

5840 L.D A, (VFARO+2) 
5845 LD C,A 

5850 LD A, (VF ARO+4) 
S855 LD D,A 

9B60 LD A, (VF ARO+46) 
5865 LD E,A 

3870 XLINE LD (YO+1) ,BC 
5875 LD (XO) ,BC 
5880 LD (Yit1) ,DE 
5885 LD (X1),DE 
5890 L.D A,o 

5895 LD (XO) ,A 
5900 LD (X1),A 
S905 LD (YO) ,A 
5910 LD (Y1),A 
S915 LD (DX) ,A 
5920 LD HL, (X1+1) 
5925 LD BC, (XO+1) 
3930 OR A 

S935 SBC HL.,BC 

5940 L.D (DX) ,HL 
S945 LD (OLDDX) ,HL 
5950 L.D HL, (Y1+1) 
5955 LD BC, (YO+r1L) 
5960 OR A 

5965 SBC HL,BC 

3970 LD (DY) ,HL 
5975 LD (OLDDY) , HL. 
5980 CALL. SDIFF 

5985 NPOIN LD A, (YO+1) 
S99O LD B,A 

5995 LD D,A 

6000 LD A, (XO+1) 
6005 LD C,A 

6010 LD E,A 

6015 CALL. FLOT 

6020 INVFT OR CHL} 

4025 LD CHL? A 
6030 CALL LFOIN 

6035 RET Z 

6040 GNXFT LD HL, (XO) 
6045 LD BC, (OLDDX) 
6050 ADD HL,BC 
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6055 
6060 
S065 
6070 
S075 
60B0 
6085 
6090 
6095 
6100 
6105 
6110 
6115 
61230 
6125 
S130 
6135 
6140 
6145 
6150 
6155 
6160 
61465 
6170 
6175 
4180 
6185 
6190 
6195 
6200 
6205 
6210 
6215 
6220 
6225 
6230 
6235 
6240 
6245 
6250 


62355 


6260 


6265 
6270 


LFOIN 


SDIFH 
SDIFG 


SDIFA 


(XO) J HL 
HL., (YO) 
BC, (OLDDY) 
HL, BC 

(YO) JHE 
A, (YO+1) 

D 
NZ,NFOIN 
A, (XO+1) 

E 

Z,GNXET 
NFOIN 

A, (XO+1) 
EA 

A, (X1+1) 

BE 

NZ 

A, (YO+#1) 
EA 

A, (Y1+1) 


HL, (DX) 
A,H 

OQ 
Z,SDIFA 
255 

NZ 

HL, (DY) 
A,H 

QO 
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62735 JR Z,SDIFEB 

6280 CF moo 

6285 RET NZ 

6290 SDIFB ADD HL,HL 

6295 LD (DY) ,HL. 
S00 SRA H 

63205 RR L. 

6310 L.D (OLDDY) ,HL 
6315 LD HL., (DX) 
6320 ADD HL,HL 

6325 LD (DX) , HL. 

635350 SRA H 

6335 RR L 

6340 L.D (OL.DDX) , HL 
6345 JR SDIFH 
Operation of PLINE 


As written, PLINE expects four value parameters in the REM statement, 
specifying the X,, Y, and X,, Y, points between which the line is to be 
drawn/plotted. These values are collected by OPARS and loaded without 
checking for validity into BC and DE. 


XLINE 


XLINE is another entry into the routine used by DRAWL, see below, 
which draws a series of lines. B, C, D, E are loaded into the MS bytes of X,, 
Y,, X, and Y, and the LS bytes are cleared. Observe carefully how the 
storage is arranged and do not disturb otherwise more instructions will be 
needed. 

X, and X, are loaded into the low order bytes of HL and BC, the high 
order bytes are zero and DX is a 16 bit signed value formed from X,—X,; 
the high order byte is either zero or all 1s. 

Similarly DY is set up from Y,—Y,. The subroutine SDIFF makes the 
values of DX and DY as large as possible but not more than one quarter of 
a pixel step and puts the vaues in OLDDX and OLDDY. 


NPOIN 

Here the next point is plotted. BC (and DE) are loaded with the coordinates 
Y in B, X in C and PLOT called. INVPT, which may be an OR or XOR 
instruction, modifies the contents of the display buffer. X, and Y,, as 16 bit 
numbers, are incremented by the fractional values on OLDDX and 
OLDDY until either the new X, or Y, differs from the old as stored in DE. 
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Figure 14.1 | 


LINE TO BE DRAWN 


IF THE LINE PASSES THROUGH A PIXEL THEN THE PIXEL |S PLOTTED e 
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Flowchart 14.1 


X LINE PLINE 


B<x, 
C<Y,\( VALUE PARAMETERS 
é 


D<xX, (WITHOUT CHECKS) 
E<yY, 


LOAD X@, YO, X1 AND Y1 
SET UP 0X AND DY 


SET UP OLDDX AND OLDDY 


SET UP BC AND DE 


[Esai 


PLOT OR UNPLOT POINT (NEXT POINT ON LINE) 
TEST FOR LAST POINT 


ALL DONE 


INCREMENT X@ BY OLDDX 
INCREMENT Y BY OLDDY 
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This newly computed point is now plotted and so on until the plotted point 
coincides with X,, Y, at which point the subroutine NPG returns with the 
Z flag set. 


SDIFF 


This happened fairly piecemeal and can be much improved. 

DX and DY can be shifted left as long as their MS bytes remain either all 
Os or all 1s and then right two places. 

Now we can draw aline between two points. You probably won’t use it at 
all because the next stage is more interesting. 


Listing 14.2 


6350 DRAWL CALL OFARS 


6355 L.D HL, (SFARO) 
6360 CALL GVAL®6 
S365 RET C 

&370 LD B,A 
6375 CALL GVALS 
6380 RET C 

6385 LD C,A 
390 DRNXF CALL GVAL8 
6395 RET C 

6400 LD D,A 
6405 CALL GYVALS 
6410 RET C 

6415 LD E,A 
6420 FUSH HL 
6425 CALL XLINE 
6430 FOF HL 
6435 FUSH DE 
6440 FOF BC 
6445 JR DRNXF 
6450 GVALS FUSH EBC 
6455 PUSH DE 
6460 NEY LD A, (HL) 
6465 INC HL 
6470 CFE fe tb beta 
6475 JR Z,JRCX 
6480 CF ee 
64835 JR Z,JRVX 
6490 SUR "oO" 
6495 LD B,A 
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6500 LD A, (BYTEYV) 
6505 SLA A 

6510 SLA A 

6515 LD C,A 

6520 L.D A, (BYTEY) 
6525 ADD C 

6530 SLA A 

6535 ADD &B 

6540 LD (BYTEV) ,A 
S45 JR NBY 

6550 JRVX L.D A, (BYTEYV) 
6555 LD BA 

6560 L.D A,O 

6565 LD (BYTEY) ,A 
6570 L.D A,E 

6575 OF A 

6580 FOF DE 

6585 FOF BC 

6590 RET 

6595 JRCX SCF 

6600 FOF DE 

6405 FOF BC 

6410 RET 


6615 BYTEV DEFB © 


DRAWL: Draw a list of lines 


DRAWL has but one parameter, a string whose contents is a list of digits 
and commas which are interpreted as being X, Y pairs and the routine 
draws from pair | to pair 2 to pair 3 and so on to the end of the list. Note 
again that there are no validity checks on the sizes of the values except that 
GVAL8 only passes the LS 8 bytes of whatever value it finds; these checks 
can be inserted if you need them. 

OPARS collects one string parameter and then GVALB8 recovers byte 
values from the string in a very primitive manner to load C, B, E, D for the 
call of XLINE to draw a line from BC to DE. 

DE is transferred into DE and DE loaded with the next point position 
and the line BC to DE drawn; the process continues till GVAL8 exits with 
the carry flag set as a result of the exhaustion of the data string. 


GVAL8 


This is entered with HL pointing into the parameter string; A is loaded with 
the next character which is assumed to be: 
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Flowchart 14.2 


DRAWL. 


COLLECT HEAD ADDRESSES 
j OPARS OF STRING 


HL= SPAR® HLPOINTS TO FIRST BYTE 


ELA 
| X LINE DRAW FROM 
BCTO DE 


BC= DE 


STORE BC + DE 


A= (HL) READ BYTE FROMSITRING 
+1 MOVE TO NEXT BYTE 


YES END OF STRING 
SET Cy FLAG 


Ala" 
B=A A= BYTEV 
BYTEV=BYTEV #10+B BYTEV = @ 


CLEAR Cy FLAG 


N.B. THE STRING IS ASSUMED 
TO BE WHOLLY CORRECT 
THERE ARE NO CHECKS FOR 
OVERFLOW OR NON DIGITS 
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a’’ marking the end of the string, 


or a, marking the end of a value 
or a digit. Non digits are not rejected but macerated. 
BYTEV: BYTe EValuated 


This is formed by shifting and adding to multiply by 10 and then adding in 
the binary value of the character, assumed to bea digit. There are no checks 
and the process continues till a comma is read. 

Now we can draw lines what about undrawing them? 

This is not too difficult. Change the OR (HL) at INVPT (invert plot) to 
XOR (HL) and all will be well so long as we retrace our steps precisely. 
Since there are, or may be, many points where this change is to be made the 
subroutine IVERT contains what amounts to alist of bytes which are to be 
changed. Repeated calls of IVERT change backwards and forwards; for 
those of us who get lost there is SVERT which sets all such options to OR 
for draw. 


Listing 14.3 


6620 IVERT LD Aly CINVET) 


6625 LD B,A 

5630 LD A, (CHNGE) 
6635 LD CINVFT) ,A 
6640 LD CINVRX) 5A 
5645 LD A,B 

6650 LD (CHNGE) ,A 
4635 RET 


6660 CHNGE XOR (HL) 
6465 SVERT LD A, CINVFT) 


6470 LD BA 

6475 LD A, (XOROF) 
6480 CF OB 

6685 RET NZ 

6490 CALL IVERT 
6495 RET 


6700 XOROF XOR (HL) 


MOVEC 


This move cursor routine operates by plotting and unplotting a diamond of 
points. For faster movement you must either increment the cursor position 
by more than one pixel step or flit from tile to tile. 
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The basis is an IFKEY call which operates as follows: 


5,6,7 & 8 keys move the cursor in the obvious directions 
sets slow movement 
sets fast movement 
sets single step movement 
causes the routine to exit, and yield up the cursor position. These 
keys are all in lower case. 


Ta x HY 


A call LET L = USR... assigns to L, when the p key is operated, the 
current cursor position which may be unravelled by the BASIC program; 
prolonged depression of the key causes repeated outputs of the same 
position. On the first call the cursor is positioned near centre screen but 
repeated calls pick up the cursor from its last known position. 


Listing 14.4 


4705 MOVEC CALL SVERT 


6710 CALL CURSK 
6715 CALL IVERT 
6720 MFAST LD Ay i 

6725 LD (23561),A 
6730 LD (23562) ,A 
6725 CIFEE CALL IFEEY 
&740 DEFER "3" 

6745 JF MRGHT 
67350 DEFER "3" 

6735 JF MLEFT 
&74O DEFR "7" 

6765 JF MUPUP 
6770 DEFE "6" 

6775 JF MDOWN 
&780 DEFB "p" 

6785 JF MEXIT 
6790 DEFB "" 

6795 JF MFAST 
6800 DEFB "s" 

6805 JF MSLOW 
46810 DEFE ‘yx " 

6815 JF MSTEF 
4820 NOF 

6825 MSTEF LD A255 
6830 LD (23561) ,A 
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6835 
6840 
6845 
6850 
6855 
6860 
6865 
6870 
6875 
6880 
6885 
6890 
5995 
S900 
6905 
6910 
6915 
6920 
6925 
5930 
6935 
6940 
6945 
6950 
6955 
6960 
6965 
6970 
6975 
6980 
6985 
6990 
6995 
7OOO 
7005 
7OLO 


7O1S 


7O2O 
7025 
7ORO 
7OR5 
7O4O 
7045 
7OSO 
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MFASU 


MSLOW 


MRGHT 
MRL 1 


MLEF T 
MRLA 


MUPUF 
MUPL 4 


MDOWN 
MDWNA 


CURSX 
CURSY 
CIFEF 


FLOA 


FLOE 


FLOC 


FPLOD 


FLOAT 


DEFEB 
DEFB 
DEFEB 
DEFR 
DEFB 
DEFB 
DEFW 


(23562) ,A 
CIFKE 
A,10 
MFASU 

A, (CURSX) 
A 
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Z,MRLA 
(CURSX) ,A 
CIFEF 

A, (CURSX) 
A 

Z MRL 
(CURSX) ,A 
CIFEF 

A, (CURSY) 
A 

Z,MDWNA 
(CURSY) ,A 
CIFEF 

A, (CURSY) 
A 

1988 
Z,MUFLA4 
(CURSY) ,A 
CIFEF 

125 

88 

cross 
IVERT 
CURSR 
IVERT 
CIFKE 

254 

254 

254 

+2 

+2 

+2 

+2 

254 


QO 


7O3S 
7060 
7965 
7O70 
7O735 
7O80 
7985S 
7O90 
7O9S 
7100 
7105 
7110 
7115 
7120 
7125 
7130 
7135 
7140 
7145 
7150 
71355 
7160 
7165 
7170 
7175 
7180 
7185 
7190 
7195 
7200 
7205 
7219 
7215 
7220 

229 
7230 
Tea 
7240 
7245 
7250 
7255 
7260 


PLOBT 
FLOCT 
FLODT 
CURSR 


CROSS 


XPLOT 
INVRX 


MEXIT 


DEFW © 
DEFW © 


LD BC, (CURSX) 
LD HL, (PLOA) 
ADD HL,BC 

LD  (PLOAT) HL 
LD HL, (PLOB) 
ADD HL,BC 

LD  (PLOBT) ,HL 
LD HL, (PLOC) 
ADD HL,BC 

LD  (PLOCT),HL 
LD HL, (FLOD) 


ADD HL,BC 
LD (PLODT) ,HL 
CALL CRASS 

RET 

LD BC, (FLODT) 
CALL XPLOT 

LD BC, (PLOBT? 
CALL XPLOT 

LD BC, (PLOAT) 
CALL XPLOT 

LD BC, (PLOCT) 
CALL XPLOT 

RET 

CALL PLOT 

OR (HL) 

LD (HL),A 
RET 

CALL SVERT 

POP IX 

FOP HL 

POP DE 

FOF BC 

LD BC, (CURSX) 
LD = A,S 

LD (23562),A 
LD A,35 

LD (23561),A 
JP TRAT# 
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Operation of MOVEC 


The routine is so simple that by now you should not need a flow diagram 
but be able to work directly from the listing. 

SVERT sets the plotting routine to a known state and then the Spectrum 
variables REPDEL and REPPER are set to their minimum values to give 
the fastest possible movement and the initial cursor position is plotted by a 
call on CURSR. IVERT is then called so that the next call will unplot the 
cursor diamond before plotting the second cursor position, this gives free 
non streaking movement. 

The routine IFKEY now waits until a lower case menu key is read; the 
cursor keys 5, 6, 7, 8 cause jumps to MLEFT, MRGHT, MUPUP and 
MDOWN where the cursor position bytes, CURSX and CURSY are 
modified appropriately and then prevented from running off the screen; 
the old position is unplotted and the new plotted before the return to 
CIFKE for the next key operation. 

The x, s, and f keys arrange for REPPER to be loaded with the 
appropriate values. Note here that one pixel vertically covers three 
television scan lines. 


Other details 


PLOA, PLOB, PLOC, and PLOD define the four diamond points with 
respect to the cursor position so that the actual cursor plot points may be 
obtained by the addition of CURSX, considered with CURSY, as a two 
byte value to these four points. These additions give the points PLOAT, 
PLOBT, PLOCT, and PLODT which are then plotted/unplotted by 
CROSS and XPLOT (according to the state of INVRX which is set by 
IVERT or SVERT). 

When p is pressed, the routine exits through MEXIT which restores all 
the registers, except BC which it sets to the CURSOR position. As is usual 
with my routines the positions of byte/word declarations is important. 


DRAWA: Draw Array 


With this subroutine and MOVEC you can build a simple drawing 
program as sketched out in Listing 14.5b. 

DRAWL looks for its data as point values in a REM parameter list. 
DRAWA isa variant on the same theme but this time the data is to be found 
in a two dimensional byte array which must be defined as: 


DIM ?$(..., 2) 


where ? is any suitable array reference and ... is as large as need be. The 
character pair ?$(p,1) and ?$(p,2) contain the x and y plot values for the 
point p as one byte values. If the y value is off screen the point is omitted; 
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this enables a line sequence to be broken as required. The insertion of the 
off screen marker is a matter of convenience. 


Listing 14.5a 


7245 DRAWA CALL. FPCALL 


Party L.D HL, (PARMO) 
7275 LD (DPL+1) ,HL 
7e28O DEL LD A, (DPL+1) 
7285 AND 128+64+22 
F290 CF 128+64 
FERS JF Z2,DL1 

7200 ERX40 Lp DE ,40 
FSO CALL. ERREX 
7310 Dit L.D HL, (DFL+13 
7315 INC HL 

FS20 L.D (DPLB+2) , HL 
7325 DELLE LD BC, (DFLA+23) 
a INC HL 

33 INC HL 
7FS4Q LD A, CHL) 
734s CF 2 
735Q JR Z,DL2 
73355 ERX41 Lp DE,41 

7F3GQ CALL ERREX 
7365 DL? INC HL 

PS7O INC HL 

F375 INC HL 

7380 L.D A, CHL) 
7385 CF = 

F39Q dR NZ, ERX42 
F3ERS INC HL 

F4OQ L.D A, CHL) 
7405) CF o 

7410 JR NZ ,ERX42 
74s INC HL 

7430 PUSH HL. 

74235 L.D HL, -6 
7430 ADD HL,BC 
74S FUSH HL. 

7440 FOF BC 

744s FOF HL 


7450 NXPFR LD (DFLCO+2) ,HL 
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7455 INC HL 
7440 INC HL 
7465 LD (DPLD+2) ,HL 
7470 DEC BC 
7475 DEC BC 
7480 BIT 7,5 
7485 RET NZ 
7490 FUSH BC 
7495 PUSH HL 
7500 DPLC LD BC, (DPLC+2) 
7505 LD A,E 
7510 LD B,C 
7515 LD 46C,A 
7520 DFLD LD DE, (DPLD+2) 
7525 LD” -A,D 
7530 LD D,E 
7535 LD  E,A 
7540 LD A,E 
7545 AND 128+44 
7550 CF =. 128+64 
7555 JR  Z,EXT 
7560 LD A,c 
7565 AND 128+64 
7570 CP = 128+64 
7575 JR  -Z,EXT 
7580 CALL XLINE 
7585 EXT POF HL 
7HPO FOF BC 
7595 JR  NXFEPR 
7600 ERX42 LD DE,42 
7605 CALL ERREX 


Listing 14.5b 


30 LET b=250 
41 DIM k¥(b,2) 

42 FOR x=1 TO b 

45 LET k#(x,1)= CHR# 255 
44 LET k#(x,2)= CHR# 255 
45 NEXT x 

50 LET keo 


51 LET ol =0 
oo LET 1= USR MaVeEC 
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54 REM read cursor postian 

56 FRINT AT 0,0;" "; PRINT AT O, 
Os;l: PORE 23560,255 

S7 [IF l=al THEN LET 165535 

98 LET k=k+1 

59 LET k#(k,2)= CHR# INT (1/256) 

60 LET k#(k,1)= CHR INT (1-256%¢( INT (17 
2uO))) 

61 IF k=1 THEN GO TO 58 

62 LET m= USR drawa 

63 REM k#¥(): 

64 LET ol=1 

65 FRINT AT 0O,43;k 

66 GO TO Ss 


Operation of DRAWA 


PCALL collects the parameter REM statement and the first parameter 
only is used. It is checked to be a character array exactly as specified; error 
40 if not a character array, error 41 if not two dimensional and error 42 if 
the second dimension is not two. 

At NXPPR the next (or first) point pair is obtained. 

HL points to the first byte pair, DPLC is a computed load instruction, 
HL is moved on two bytes and DPLD is computed to load the next pair into 
DE. This will be the first byte pair next time round. 

The byte pairs BC and DE must be swapped around for the call of 
XLINE. The swapping could be omitted but then the point pairs in the 
array parameter would need to be reversed and this is not the normal 
convention. 

BC and DE, once set up, are checked to ensure that they are both on 
screen. If either is off the screen the line drawing routine XLINE is omitted 
and the next point pair is obtained for as long as data remains as tested for 
by BC greater than zero. 


BASIC drawing program 


This program using only MOVEC and DRAWA routines enables the 
drawing of quite complex figures. The keys operate as specified for 
MOVEC; ‘p’ causes the cursor position to be transferred into 1 and hence 
to the kth slot of k$( ) , a repeated point causes the off screen marker to be 
inserted and the cursor may then be moved to the head of the next desired 
line. 

I leave you with the problem of how to break out of the drawing routine 
so that you can save k$( ). Hint: you might reserve the bottom of the 
screen for a menu of some sort. 
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Flowchart 14.3 


DRAWA 


COMPUTE LOAD BG WITH LENGTH 


2"4 DIMENSION 
NOT 2 
SET BC = N° OF DATA BYTES -1 


ERROR 42. 
HL POINTS TO FIRST BYTE. 
(HL POINTS TO NEXT BYTE PAIR) (orn 


COMPUTE LD BC INSTRUCTION 
FOR FIRST POINT DATA - DPLC 
COMPUTE LD DE INSTRUCTION 
FOR SECOND POINT DATA -DPLD 


DECREMENT DATA BYTE COUNTER 


LOAD BC 


EXCHANGE BYTES FOR XLUNE POINT X,Y, 


POINT X,Y, 


RESTORE HL, BC 
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Synopsis 


DRAWL allows you to draw a series of connected lines from point 1 to 
point 2 to point 3... These points are specified as x, y pairs in the REM 
parameter statement which may be of any length, eg REM: ‘‘x1, yl, x2, y2, 
x3, y3, x4, y4,... xn, yn,’’. 

DRAWA is similar to DRAWL but the data should be supplied in a 
character array of xy pairs. Points outside the display area are not plotted 
so lines may be broken by inserting an ‘off screen’ point in the array. 

MOVEC uses the 5, 6, 7, 8 keys to move a cursor around the screen. The 
‘p’ key causes the routine to exit with the current position of the cursor; the 
x, Sand f keys allow single step, slow and fast cursor movement. 

A BASIC drawing program is listing in Listing 14.4; this is for you to 
elaborate as you wish. 
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Miscellaneous 


Here are some tit-bits which are nice to know or think about but do not 
warrant a chapter to themselves. 


BCD or Binary Coded Decimal 


A form of number representation and arithmetic, believed to be of 
American origin and dubious parentage. It enabled a salesman to say toa 
prospective victim: ‘‘‘but our machine can do decimal arithmetic — you 
shouldn’t bother with one of theirs. Their’s can only do (nasty, 
complicated, difficult) binary’’’. 

Each decimal digit can be represented by four bits with the values 8, 4, 2, 
1 in 8421 BCD. (There is another form 4421 BCD). The Z80 chip will 
handle BCD arithmetic at two digits per byte if, after each addition or 
subtraction you insert a DAA operation (Decimal Arithmetic Adjust) and 
write a special number print routine. 

I regard the presence of BCD within a machine as something best 
overlooked; however, many pieces of electronic equipment do make 
available BCD coded signals, four wires per decimal read out digit, so that 
they may be interfaced with computer systems. 


Modifications 


All I have been able to do, in this book, is point you in the proper direction. 
No book is ever going to solve all your problems for you, but by way of 
illustration I have included some code extras which I leave you to 
understand. 


Listing 15.1 


7610 DEMOL CALL OFARS 


7615 CALL FCALL. 

7620 CALL FIDL1I 

7625 JF SATTR+3 
7630 FIDLi LD HL, (FARMO) 
7635 LD BC ,3 
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7464Q ADD HL,BC 
7645 L.D DE , VF ARO+8 
7650 LDI 

76585 RET 

7660 DEMOS CALL FCALL 
7465 CALL. FIDL? 
7670 JF SATTR+S 
7675 FIDLS LD HL, (FARMO) 
7680 L.D BRC ,8 
7685 ADD HL,BC 
7690 L.D DE , VF ARO 
7695 CALL LDFR 
77OO CALL. LDFR 
77OS CALL LDFF 
F7FAO CALL LDFER 
7715 CALL. LDFR 
7720 RET 

77295 LDER LDI 

7730 LD BC, 4 
77AS ADD HL, BC 
774AQ INC DE 

7745S RET 

7750 END 

DEMO1 


This enters SATTR after the call of OPARS and PCALL. The REM 
statement it expects is: 


REM k: 0, 0, 15, 7, 


where k is an (integer) attribute and the constants are a tile region 
descriptor. 


DEMO2 
This also enters SATTR but its REM statement is: 
REM @( ): 


and the first five entries in a( ) are the tile descriptors and the required 
attribute. These must all be integers. 

Both use fiddle subroutines. Note how simple they are, work out how 
they operate, and have fun doing your own. 
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Multiple entry 
With a large suite of programs a very nasty state of affairs can occur: 


Program A outputs to display 1 
Program B outputs to display 2 


There is a common subroutine C, deep in the depths, doing the actual 
display output. 

A is outputting to the display when the display goes faulty and reports to 
C, which outputs an error message to the operator and waits for the display 
fault to be cleared. 

Program B now outputs, using common subroutine C, and promptly 
fouls everything up something rotten unless C is specially written to take 
care of the problem. 

The usual technique is first to estimate the number of multiple calls that 
can be running at the same time, add 50% (or more) and then set up that 
number of ‘pages’, perhaps using the IX register or its equivalent, for all 
the workspace needed for one entry. Each cell is then allocated a ‘page’ 
which is released when that call terminates. If no room is available the 
calling program must be informed so that it can wait or whatever until the 
call can be accepted. 


Recursion — or flying the Ouzlum bird 


Recursion is the calling of a subroutine by itself. This may happen by 
accident in large programs or be deliberate as a result of a quest for reduced 
code or otherwise. It almost always demands large amounts of stack space. 

Ordinarily, the call of itself will destroy the workspaces and return 
address, so the subroutine must be deliberately designed to cope with this. 
In some ways the problem is similar to that of Multiple Entry but here the 
data is all stored on the stack for entry and a section of the stack is used for 
workspace as well. The basic technique is illustrated in Figure 15.1. You 
must ensure that the subroutine call on itself must be conditional and that 
the condition fails so the subroutine can exit and thread its way back to the 
outside world. If you do not the system, like the Ouzlum bird, will have a 
nasty accident. 


Notes on the machine code and the assembler 
All the mnemonics for the operation codes are as standard. The ‘hidden’ 
operations, ie those for which the hardware operates but whose existence 
is not official, are used. 

The directive, assembler driving, mnemonics which are used are: 


DEFB defines one byte as a decimal number or ASCII character 
DEFS defines a series of BYTES by using an ASCII string 
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Flowchart 15.1 


PUSHHL  tinpyr p ETERS EMOR 
Pare Be ONTO THE STACK ADDRESSES 
PoP BC Jourrur PARAMETERS ee on 
ibis a a ee 
THEN IN RECUR aes ~. 
PCS“ Cor 
RECUR LD HL,-19 P t—‘“t;tSSC*r‘SS fs SPACE 
ADD HL, SP LT C—C‘C‘id: 
LD SP,HL— Paes 
Lb Crit) aL, / neyo 
LD 1X(TM1) aes 


tesa pee as RETURN gS P_AT ENTRY 
[BODY OF THE SUBROUTINE TO SUBROUTINE 
| REFERENCING DATA VIA |X | B | 


AND OFFSETS 8 
| 5 U2 ucts 
| conDITIONAL CALL ON RECUR 

Z HIGH MEMORY 

| MORE SvBROUTINE ADDRESSES 

LD (TM4), IX pea 

ee HLATM!) POINT 10 RETURN ADDRESS 

LD BC,-19 Y REVERSIN 

ADD HL, BO THE. INCREMENT 

LD SP HL AT THE ENTRY 

RET [TM1 1S SOME. WORKSPACE] 


> IF THE CONDITIONAL CALL IS NOT MET SOON ENOUGH, 
THE SYSTEM WILL CRASH 
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DEFW defines a word of two bytes 

END — specifies the end of the machine code 

EQU requires a label, which is assigned the value in its address 
field. This is usually the address of a Spectrum system 
variable. 

ORG specifies the head address of the assembled code 


A single byte value may be specified by a decimal value (0O—255) or an 
ASCII character enclosed within double quotes. Note that LD ad 
loads A with the ASCII code for‘’’’. 


Code — do’s and don’ts 


Assemble the code to run at high memory addresses but leave enough room 
between the end of your code and the Spectrum UDG pointer location for 
the stack (see Spectrum manual Chapter 24 page 165) ie at the high address 
end of WORKSP. In general you will be alright if the end of your code is at 
about 63500 with a 48K machine. 

Never use absolute addresses (numerical values) within your code. 
Absolute addresses should only be used when addressing Spectrum 
variables, (as detailed in Chapter 25 pages 173-176 of the manual) or 
specific parts of the ROM. 

Keep notes on all your programming, and your errors! 

Make all names as mnemonic as you can. 

Write straightforward programs whenever you can. (A program which 
works is better than none at all, and few drivers ever look under the 
bonnet.) 

Have a very clear idea of what you want to do before you start. 
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The select index is a guide to the main discussions of these subjects. The 


figures given are for the first page(s) on which entries appear. 
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B 
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Cc 

Clarity 157 
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Complexity 84 
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(see also STACK) 

D 

DAA instruction 153 
Data 12, 23 
Data structure(s) 26, 66 
DEMO1 154 
DEMO2 154 
Display clearing 35 
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Documentation 12, 47, 84 
DRAWA 146 
Drawing 133 
DRAWL 140 
E 

Environment 13 
Errors 9, 12, 22, 66, 77 
Error return(s) 77 
F 

Floating point 26, 97 
Flow diagrams 9 and examples 
FPcomparision 101 
G 

GVAL8 140 
I 

IFKEY 38 
Instructions 12,15 
Interface 65, 153 
L 

Learning 35 
LINE 48,50 
Loading 157 
M 

MAP$ 61 
Modifications 153 
MOVEC 142 
Mnemonics 155 
Moving cursor 142 
Multiple entry routines 155 
Multiple entries 107 
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N 
Numbers 


O 
Octal 
OPARS 


P 

Passing data 
Passing parameters 
PCALL 

Pixel locating 
PLINE 

PLOT 

PRIN 

PRT8 


R 
Recursion 
Reliability 
RESLN 
RPORT 


S 
SATTR 
Scaling 
SDIFF 
SEBIT 


Printed in England by Commercial Colour Press, London E7. 
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55 
111 


41, 52 
80, 83, 107 
84 


Shifting 
Simplicity 
Size 
Specification 
Speed 
SORTF 
Sorting 
Stack 
SUPLN 


T 
Testability 


U 
Un-Drawing 


vV 
VAR$ 
Verification 


WwW 
Waiting 


Waiting for key 


Writing text 


(displaying only) 


x 
XLINE 
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